nestjs-best-practices

NestJS のベストプラクティス

本番環境に対応した NestJS アプリケーションを構築するための包括的なガイドです。セキュリティ、アーキテクチャ、パフォーマンス、バリデーション、データベース操作、認証、高度なパターンを網羅した、13 カテゴリ・26 ルールが含まれています。

適用するタイミング

次の場合に、これらのガイドラインを参照してください。

• 新しい NestJS モジュール、コントローラー、サービスを作成するとき
• 認証と認可を実装するとき
• Prisma のデータベース操作を設定するとき
• DTO とバリデーションパイプを作成するとき
• ミドルウェアやガードを追加するとき
• エラー処理とロギングを実装するとき
• ベストプラクティスに沿って NestJS コードをレビューするとき
• 既存の NestJS アプリケーションをリファクタリングするとき

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

優先度	カテゴリ	影響度	プレフィックス
1	セキュリティ	CRITICAL	security-
2	パフォーマンス	HIGH	performance-
3	アーキテクチャ	HIGH	architecture-
4	エラー処理	HIGH	error-handling-
5	バリデーション	CRITICAL	validation-
6	データベース	CRITICAL	database-
7	認証	CRITICAL	auth-
8	API	MEDIUM	api-
9	設定	CRITICAL	config-
10	テスト	MEDIUM	testing-
11	デプロイ	MEDIUM	deployment-
12	ミドルウェア	MEDIUM	middleware-
13	高度なパターン	HIGH	advanced-

クイックリファレンス

1. セキュリティ（CRITICAL）

• security-cors-whitelist - 許可リストに登録されたオリジンのみで CORS を有効にする
• security-dependency-audit - bun で依存関係のセキュリティ監査を定期的に実施する
• security-helmet-headers - セキュリティヘッダーに Helmet ミドルウェアを使用する

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

• performance-redis-caching - 頻繁に使用するデータを Redis でキャッシュする

3. アーキテクチャ（HIGH）

• architecture-short-functions - 関数を短く保ち、単一の目的を持たせる
• architecture-feature-modules - 機能ごとにコードをモジュールに整理する
• architecture-no-dead-code - 未使用のコードと依存関係を削除する
• architecture-thin-controllers - 単一責任の原則に従い、コントローラーとサービスを分離する
• architecture-naming-conventions - 一貫した命名規則を使用する
• architecture-event-driven - 疎結合を実現するためにイベント駆動型アーキテクチャを使用する

4. エラー処理（HIGH）

• error-handling-exception-filter - グローバル例外フィルターを有効にする
• error-handling-structured-logging - 適切なロギング戦略を実装する

5. バリデーション（CRITICAL）

• validation-custom-pipes - クエリパラメーターを変換するカスタムパイプを作成する
• validation-dto-validation - DTO と ValidationPipe ですべての入力を検証する

6. データベース（CRITICAL）

• database-parameterized-queries - SQL インジェクションを防ぐためにパラメーター化クエリを使用する（Prisma v7）

7. 認証（CRITICAL）

• auth-password-hashing - 安全なパスワードのハッシュ化に Bun 組み込みの Crypto を使用する（argon2/bcrypt）
• auth-route-guards - ルートの保護にガードを使用する

8. API（MEDIUM）

• api-cursor-pagination - 大規模なデータセットにはカーソルベースのページネーションを使用する
• api-swagger-docs - Swagger/OpenAPI ドキュメントを生成する

9. 設定（CRITICAL）

• config-no-secrets - シークレットをハードコードせず、環境変数を使用する

10. テスト（MEDIUM）

• testing-unit-tests - 包括的なユニットテストを作成する

11. デプロイ（MEDIUM）

• deployment-health-checks - ヘルスチェック用エンドポイントを実装する

12. ミドルウェア（MEDIUM）

• middleware-compression - レスポンス向けの圧縮ミドルウェアを有効にする
• middleware-rate-limiting - すべてのルートにレート制限を実装する

13. 高度なパターン（HIGH）

• advanced-lazy-loading - 重要度の低いモジュールを遅延読み込みする
• advanced-scheduled-tasks - cron ジョブとスケジュール済みタスクに @nestjs/schedule を使用する

使用方法

詳細な説明とコード例については、各ルールファイルをお読みください。

rules/security-cors-whitelist.md
rules/auth-route-guards.md
rules/validation-dto-validation.md
rules/_sections.md

各ルールファイルには、以下が含まれています。

• 実装手順を順を追って説明する「AI エージェント向け」セクション
• コードレビュー用のクイックリファレンスチェックリスト
• ファイルの場所を示した❌ WRONG と ✅ CORRECT のパターン
• bun add を使用したインストールコマンド
• NestJS + Prisma の包括的なコード例
• セキュリティとパフォーマンスに関する考慮事項

重要なパターン

エージェントに適した形式

すべてのルールは、AI エージェント向けに最適化されています。次の内容が含まれています。

• ファイルの場所を明示（例：src/users/users.service.ts）
• 手順を順を追って説明する「AI エージェント向け」セクション
• ✅ CORRECT と ❌ WRONG のパターン比較
• クイックリファレンスチェックリスト
• 明確なインストール手順

技術スタック

• フレームワーク：Express/Fastify アダプターを使用した NestJS
• ランタイム：Bun（ネイティブの暗号化、スケジューリング）
• データベース：Prisma v7（sql テンプレートタグ、インタラクティブトランザクション）
• バリデーション：class-validator + class-transformer
• セキュリティ：Helmet、CORS の許可リスト、レート制限
• スケジューリング：cron/interval デコレーターを使用した @nestjs/schedule
• イベント：疎結合を実現する EventEmitter2

完全版のコンパイル済みドキュメント

すべてのルールを展開した完全なガイドについては、AGENTS.md をご覧ください。

ビルドコマンド

cd packages/nestjs-best-practices-build
bun install
bun run build      # Generate AGENTS.md
bun run validate   # Validate rule files
bun run dev        # Build and validate

統計情報

• NestJS 開発のあらゆる側面を網羅する13 のセクション
• 影響度（CRITICAL、HIGH、MEDIUM）で優先順位付けされた26 のルール
• Prisma v7 に対応したデータベースパターン
• Bun ランタイムのネイティブ機能（Crypto.hashPassword、@nestjs/schedule）
• 自動コード生成とレビューに最適化されたエージェント向け設計