NestJS TypeScript 開發規範

# NestJS TypeScript 開發規範 ## 基本原則 - 所有程式碼和文檔使用英文 - 始終聲明每個變數和函數的類型（參數和返回值） - 避免使用 any 類型 - 使用 JSDoc 記錄公共類和方法 - 函數內不留空行 - 每個文件一個導出 ## 命名規範 - 類使用 PascalCase - 變數、函數和方法使用 camelCase - 文件和目錄名稱使用 kebab-case - 環境變數使用 UPPERCASE - 避免魔術數字，定義常量 - 函數名稱以動詞開頭 - 布林變數使用動詞（如 isLoading、hasError、canDelete） - 使用完整單詞而非縮寫，拼寫正確 ## 函數規範 - 編寫短小精悍的單一職責函數（少於20條指令） - 使用動詞命名函數 - 避免嵌套塊： - 使用早期檢查和返回 - 提取到工具函數 - 使用高階函數（map、filter、reduce 等） - 使用默認參數值代替 null/undefined 檢查 - 使用 RO-RO 模式減少函數參數 - 使用單一抽象層級 ## 數據處理 - 不要濫用原始類型，將數據封裝在複合類型中 - 避免在函數中進行數據驗證，使用帶內部驗證的類 - 偏好數據不可變性： - 使用 readonly 修飾不變的數據 - 使用 as const 修飾不變的字面量 ## 類設計 - 遵循 SOLID 原則 - 偏好組合而非繼承 - 聲明接口來定義契約 - 編寫小型的單一職責類： - 少於200條指令 - 少於10個公共方法 - 少於10個屬性 ## 異常處理 - 使用異常處理預期外的錯誤 - 捕獲異常應為了： - 修復預期問題 - 添加上下文 - 否則使用全局處理器 ## NestJS 特定規範 - 使用模塊化架構 - 將 API 封裝在模塊中： - 每個主要域/路由一個模塊 - 一個主控制器和其他次要路由控制器 - 使用 class-validator 驗證 DTO - 每個實體一個服務 - 核心模塊包含 Nest 工件： - 全局過濾器、中間件、守衛、攔截器 - 共享模塊包含模塊間共享服務