nestjs-best-practices

NestJS 最佳實踐

NestJS 應用程式的全面最佳實踐指南。包含 10 個類別共 40 條規則，按影響程度排序，以引導自動化重構與程式碼生成。

何時套用

在以下情況參考這些指南：

• 撰寫新的 NestJS 模組、控制器或服務
• 實作驗證與授權
• 審查程式碼的架構與安全性問題
• 重構現有的 NestJS 程式碼庫
• 最佳化效能或資料庫查詢
• 建構微服務架構

規則類別優先順序

優先順序	類別	影響程度	前綴
1	架構	關鍵	arch-
2	依賴注入	關鍵	di-
3	錯誤處理	高	error-
4	安全性	高	security-
5	效能	高	perf-
6	測試	中高	test-
7	資料庫與 ORM	中高	db-
8	API 設計	中	api-
9	微服務	中	micro-
10	DevOps 與部署	低中	devops-

快速參考

1. 架構（關鍵）

• arch-avoid-circular-deps - 避免循環模組依賴
• arch-feature-modules - 按功能而非技術層組織
• arch-module-sharing - 正確的模組匯出/匯入，避免重複提供者
• arch-single-responsibility - 專注的服務，避免「上帝服務」
• arch-use-repository-pattern - 抽象資料庫邏輯以利測試
• arch-use-events - 事件驅動架構以解耦

2. 依賴注入（關鍵）

• di-avoid-service-locator - 避免服務定位器反模式
• di-interface-segregation - 介面隔離原則（ISP）
• di-liskov-substitution - 里氏替換原則（LSP）
• di-prefer-constructor-injection - 建構子注入優於屬性注入
• di-scope-awareness - 理解單例/請求/瞬態範圍
• di-use-interfaces-tokens - 使用注入權杖代表介面

3. 錯誤處理（高）

• error-use-exception-filters - 集中式例外處理
• error-throw-http-exceptions - 使用 NestJS HTTP 例外
• error-handle-async-errors - 正確處理非同步錯誤

4. 安全性（高）

• security-auth-jwt - 安全的 JWT 驗證
• security-validate-all-input - 使用 class-validator 驗證
• security-use-guards - 驗證與授權守衛
• security-sanitize-output - 防止 XSS 攻擊
• security-rate-limiting - 實作速率限制

5. 效能（高）

• perf-async-hooks - 正確的非同步生命週期鉤子
• perf-use-caching - 實作快取策略
• perf-optimize-database - 最佳化資料庫查詢
• perf-lazy-loading - 延遲載入模組以加快啟動速度

6. 測試（中高）

• test-use-testing-module - 使用 NestJS 測試工具
• test-e2e-supertest - 使用 Supertest 進行端到端測試
• test-mock-external-services - 模擬外部依賴

7. 資料庫與 ORM（中高）

• db-use-transactions - 交易管理
• db-avoid-n-plus-one - 避免 N+1 查詢問題
• db-use-migrations - 使用遷移管理綱要變更

8. API 設計（中）

• api-use-dto-serialization - DTO 與回應序列化
• api-use-interceptors - 橫切關注點
• api-versioning - API 版本化策略
• api-use-pipes - 使用管道進行輸入轉換

9. 微服務（中）

• micro-use-patterns - 訊息與事件模式
• micro-use-health-checks - 健康檢查以利編排
• micro-use-queues - 背景任務處理

10. DevOps 與部署（低中）

• devops-use-config-module - 環境設定
• devops-use-logging - 結構化日誌
• devops-graceful-shutdown - 零停機部署

如何使用

閱讀個別規則檔案以取得詳細說明與程式碼範例：

rules/arch-avoid-circular-deps.md
rules/security-validate-all-input.md
rules/_sections.md

每個規則檔案包含：

• 為何重要的簡要說明
• 錯誤的程式碼範例與說明
• 正確的程式碼範例與說明
• 額外背景與參考資料

完整彙編文件

完整指南（含所有規則展開）：AGENTS.md