nestjs-best-practices

NestJS のベストプラクティス

NestJS アプリケーション向けの包括的なベストプラクティスガイドです。10 のカテゴリにわたる 40 のルールを収録し、影響度に基づいて優先順位を付けることで、自動リファクタリングやコード生成を支援します。

適用するタイミング

以下のような場合に、このガイドラインを参照してください。

• NestJS の新しいモジュール、コントローラー、サービスを作成する場合
• 認証と認可を実装する場合
• アーキテクチャとセキュリティの問題についてコードをレビューする場合
• 既存の NestJS コードベースをリファクタリングする場合
• パフォーマンスやデータベースクエリを最適化する場合
• マイクロサービスアーキテクチャを構築する場合

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	アーキテクチャ	CRITICAL	arch-
2	依存性注入	CRITICAL	di-
3	エラー処理	HIGH	error-
4	セキュリティ	HIGH	security-
5	パフォーマンス	HIGH	perf-
6	テスト	MEDIUM-HIGH	test-
7	データベースと ORM	MEDIUM-HIGH	db-
8	API 設計	MEDIUM	api-
9	マイクロサービス	MEDIUM	micro-
10	DevOps とデプロイ	LOW-MEDIUM	devops-

クイックリファレンス

1. アーキテクチャ（CRITICAL）

• arch-avoid-circular-deps - モジュール間の循環依存を避ける
• arch-feature-modules - 技術レイヤーではなく機能ごとに整理する
• arch-module-sharing - モジュールのエクスポートとインポートを適切に行い、プロバイダーの重複を避ける
• arch-single-responsibility - 「ゴッドサービス」ではなく、責務を絞ったサービスを使用する
• arch-use-repository-pattern - テスト容易性のためにデータベースロジックを抽象化する
• arch-use-events - 疎結合を実現するイベント駆動型アーキテクチャを使用する

2. 依存性注入（CRITICAL）

• di-avoid-service-locator - サービスロケーターのアンチパターンを避ける
• di-interface-segregation - インターフェース分離の原則（ISP）
• di-liskov-substitution - リスコフの置換原則（LSP）
• di-prefer-constructor-injection - プロパティ注入よりコンストラクター注入を優先する
• di-scope-awareness - シングルトン、リクエスト、トランジェントの各スコープを理解する
• di-use-interfaces-tokens - インターフェースにはインジェクショントークンを使用する

3. エラー処理（HIGH）

• error-use-exception-filters - 例外処理を一元化する
• error-throw-http-exceptions - NestJS の HTTP 例外を使用する
• error-handle-async-errors - 非同期エラーを適切に処理する

4. セキュリティ（HIGH）

• security-auth-jwt - JWT 認証を安全に行う
• security-validate-all-input - class-validator でバリデーションする
• security-use-guards - 認証ガードと認可ガードを使用する
• security-sanitize-output - XSS 攻撃を防ぐ
• security-rate-limiting - レート制限を実装する

5. パフォーマンス（HIGH）

• perf-async-hooks - 非同期ライフサイクルフックを適切に使用する
• perf-use-caching - キャッシュ戦略を実装する
• perf-optimize-database - データベースクエリを最適化する
• perf-lazy-loading - 起動を高速化するためにモジュールを遅延読み込みする

6. テスト（MEDIUM-HIGH）

• test-use-testing-module - NestJS のテストユーティリティを使用する
• test-e2e-supertest - Supertest で E2E テストを行う
• test-mock-external-services - 外部依存関係をモックする

7. データベースと ORM（MEDIUM-HIGH）

• db-use-transactions - トランザクションを管理する
• db-avoid-n-plus-one - N+1 クエリの問題を避ける
• db-use-migrations - スキーマ変更にはマイグレーションを使用する

8. API 設計（MEDIUM）

• api-use-dto-serialization - DTO とレスポンスのシリアライズを行う
• api-use-interceptors - 横断的関心事にインターセプターを使用する
• api-versioning - API のバージョニング戦略を使用する
• api-use-pipes - パイプで入力を変換する

9. マイクロサービス（MEDIUM）

• micro-use-patterns - メッセージとイベントのパターンを使用する
• micro-use-health-checks - オーケストレーション向けのヘルスチェックを実装する
• micro-use-queues - バックグラウンドジョブを処理する

10. DevOps とデプロイ（LOW-MEDIUM）

• 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

各ルールファイルには、次の内容が含まれています。

• 重要な理由の簡潔な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 追加のコンテキストと参考資料

完全版ドキュメント

すべてのルールを展開して1つのドキュメントにまとめた完全版ガイドについては、 リポジトリ内の AGENTS.mdをご覧ください。