ngaq-code-review

name	ngaq-code-review
description	審查C#代碼

該規範不包含前端相關。若要看前端相關代碼規範、請看 .agents/skills/ngaq-code-review-frontend/SKILL.typ

通用規範

功能正確性

功能正確性是最關鍵的。先自己通過觀察判斷是否存在缺陷。

命名規範

異步函數

異步函數不使用任何後綴、約定 最後一個參數聲明爲 CT Ct的即異步函數

函數參數

函數參數首字母也要大寫！

AOT編譯

所有代碼必須兼容AOT編譯！禁止使用不兼容AOT的寫法、 包括但不限于 運行時動態反射API, 不兼容AOT的第三方庫等。 (依賴注入的IJsonSerializer, ToolJson等是兼容AOT的)

異步函數

除非特殊情況、禁止用.Result或其他方式把異步轉同步

註釋

• AI寫的代碼要一定要有註釋。
• 註釋要讓讀者快速理解「意圖、約束、邊界條件」等等，而不是重複代碼表面含義。

添加註釋的位置

• 文件頭(可選)
• 類型(class/interface/struct/enum等)
• 方法(不管是不是public)
• 類型的成員(包括字段和訪問器 事件等等、不管是不是public)
• 函數內部實現()

函數內部實現 加註釋的要求

• 應加盡加 寧濫勿缺 尤其是難一眼看懂的複雜邏輯 包括但不限于: 分支/狀態轉換
• 函數實現內 如果可以劃分出多個子步驟時、 在每個子步驟的開頭 添加概括性註釋。 如

DoSomething() {
	// step 1: xxx
	......
	// step 2: yyy
}

禁止事項

• 不爲顯而易見的代碼添加機械式註釋。

性能檢查

批量操作

(注意、此項目約定 Bat開頭的批量查詢函數、返回順序和入參順序是一一對應的)

批量操作函數 接收的參數 首選 IAsyncEnumerable<T>。

當使用可迭代集合而非IList時、要求空間複雜度爲O(常數)。 (把可迭代集合 分批次結合 BatchCollector 使用、即使在BatchCollector內積存本批次、也把空間複雜度視爲O(常數))

對于可迭代集合、謹慎使用.ToList()或類似API 因爲這會把所有元素都載入內存! 也不要自己用foreach消費然後開List積攢起來(這和ToList其實一樣)

需要操作內部元素旹盡量使用.Select保持懶加載

注意 可迭代集合 只允許消費一遍 不允許多次消費

Stream亦同理、默認需要懶加載、不能把全部數據都一次性載入內存、不能用MemoryStream接收

調用其他批量函數的規範

• 善用 BatchCollector
• 調用支持批量操作的函數的時候 避免在for循序中多次調用且每次調用時只傳一個參數
  • 調用 接收批量對象的 函數、 你就得批量地傳對象 不能把原本成批量的數據拆成一個 逐個傳!

錯誤示例:

void fn(IDbUserCtx Ctx, IAsyncEnumerable<MyObj> Itbl, CT Ct){
	await foreach(var obj in Itbl){
		//這種情況是 拆散批量 變逐個傳 性能極差
		BatHandleObj(Ctx, ToolAsyE.ToAsyE([obj]), Ct);
	}
}

正確示例: 用BatchCollector。 除上述之外 也要檢查有無其他性能問題。 重點考慮時間複雜度和空間複雜度。

代碼架構規範

函數實現規範

• 一個函數不要超過50行、若超過則考慮拆分。
• 函數不應接收過多參數。如果參數過多就應考慮建立專門的DTO作參數或返回值。(依賴注入的構造函數除外)

面向接口

• 使用面向接口的面向對象編程。用interface來做抽象而不是父類。
• 僅用類繼承作爲代碼複用的手段、不依賴類繼承機制 作抽象。

遵守SOLID原則

單一職責

開閉

對擴展開放、對修改封閉

里氏替換

把抽象層接口的實現類替換成其他實現類 不應該影響其功能的正確性。 實現接口時應當注意這一點。實現的方法 語義和行爲要一致

接口隔離

不要強迫一個實現類實現他不該實現的方法。如果出現了這種情況即需考慮把大接口細分成小接口。

控制反轉

• 依賴抽象而不是實現。
• 適合用依賴注入的地方(如Svc,Dao,Vm等地方)就用依賴注入、不要自己new依賴。

考慮可擴展性和可維護性

禁止硬編碼

禁止字符串硬編碼鍵名。禁止魔法字符串 魔法數字。 多用 nameof / 枚舉 / 自己實現枚舉

代碼複用

• 注意代碼複用、避免重複代碼。發現有能抽取複用邏輯時要抽取複用。

若你發現一段代碼 可能具有比較廣泛的適用性 (比如一些純函數, 工具函數等): 先查找當前項目中有沒有已封裝好的現成的

• 對于已有的工具 則不要重複造輪子、直接調用現成的。
• 若無、則考慮封裝成全局的工具。

依賴注入規範

• 需要在一個模型中引用其他模塊時、使用構造函數依賴注入
• 不允許調用程序全局的 GetService<MyService>()來獲取依賴！你應該使用構造函數依賴注入
  • 除非特殊情況如 程序入口初始化, View層的 App.DiOrMk<Ctx>() 等

業務異常處理

必須使用 ItemsErr 中定義的異常種類、不要硬編碼異常信息。 若是快速開發中的臨時硬編碼異常信息 就用 Todo.I18n(異常信息)。

正確示例:

if(_UserId.IsNullOrDefault()){
	throw ItemsErr.User.AuthenticationFailed.ToErr();
}

或 快速開發時臨時硬編碼

if(_UserId.IsNullOrDefault()){
	throw new Exception(Todo.I18n("AuthenticationFailed"));
}

錯誤示例

if(_UserId.IsNullOrDefault()){
	throw new Exception("AuthenticationFailed");
	//拋其他種類的異常也不允許、要麼你就用ItemsErr中定義的強類型異常、要麼你就用Todo.I18n()
}

重點檢查位置: 檢查Svc層。 添加或修改操作 可能拋出

• ItemsErr.Common.DataIllegalOrConflict (約束違反等)
• 或其他更細分的異常

注意代碼警告

• 避免使用已過頭的API ([Obsolete])
• 注意空值安全
• 重視代碼警告

安全問題

檢查代碼中有無安全漏洞。

Owner檢查

實現了 I_Owner 接口的實體、要用 I_Owner.CheckOwner 擴展方法過一遍 來檢查Owner和當前UserId是否匹配

一致性

相似的場景應採用相似的處理、保持一致性。 除非特殊原因、若發現不一致的地方 應提出。

跨平臺要求

確保Ngaq.Core和Ngaq.Ui兩個程序集 是 平臺無關的(即跨平臺的、包括Web平臺) 禁止直接在 Ngaq.Ui 裏面使用任何 非跨平臺的API 如

• 讀寫文件(Web端不支持)
• 硬耦合特定操作系統特定API(如剪貼板等)

數據庫操作規範

• 讀寫數據庫相關的函數優先提供批量版本
• 構建Sql的操作應在Dao層寫、不能在Svc層寫
• 默認情況下、查找的數據都是不包含被軟刪除的。使用SqlSplicer時記得.WhereNonDel()
  • 如果明確希望查找的數據包含已刪除的條目、則方法要帶上WithDel後綴### 構建Sql 能用SqlSplicer就不要用事符串插值

接口調用

• 檢查有無不合適的接口調用(如誤用分頁接口當做精確查找接口用等)

其他檢查點

上述內容只列舉了幾個常見的檢查點。 對于上面未列舉 但你自己覺得有問題的 也要提出。

當代碼不符合上述規範時如何處理

默認情況下、直接把代碼中不符合規範的內容報告給用戶、不需要自行修改代碼。

如果用戶已經要求你自行迭代修改代碼 那就自行修改。改完一版之後再讀此文件對照評審。