NestJS ベストプラクティス

概要

NestJS公式ドキュメントに基づいており、モジュラーアーキテクチャ、依存性注入スコーピング、例外フィルター、class-validatorを用いたDTO検証、およびDrizzle ORM統合パターンを強制します。

使用時期

• NestJSモジュールまたは依存性注入の設計・リファクタリング時
• 例外フィルター、DTO検証、またはDrizzle ORM統合の作成時
• アンチパターンのコードレビューまたはNestJSコードベースへのオンボーディング時

指示

1. モジュラーアーキテクチャ

厳密なモジュールカプセル化に従います。各ドメイン機能は独自の@Module()である必要があります：

• 他のモジュールが必要とするもののみをエクスポート — 内部プロバイダーはプライベートのままにする
• 循環依存関係に対してはforwardRef()を最後の手段としてのみ使用 — リストラクチャリングを優先する
• 関連するコントローラー、サービス、リポジトリーを同じモジュール内にグループ化する
• クロスカッティングコンサーン（ロギング、構成、キャッシング）にはSharedModuleを使用する

強制ルールについてはreferences/arch-module-boundaries.mdを参照してください。

2. 依存性注入

ユースケースに基づいて正しいプロバイダースコープを選択します：

スコープ	ライフサイクル	ユースケース
DEFAULT	シングルトン（共有）	ステートレスサービス、リポジトリー
REQUEST	リクエストごとのインスタンス	リクエストスコープデータ（テナント、ユーザーコンテキスト）
TRANSIENT	注入ごとに新規インスタンス	ステートフルユーティリティ、クライアントごとのキャッシュ

• DEFAULTスコープをデフォルトとする — REQUESTまたはTRANSIENTは正当化される場合のみ使用する
• コンストラクタ注入を排他的に使用 — プロパティ注入は避ける
• useClass、useValue、useFactory、またはuseExistingでカスタムプロバイダーを登録する

強制ルールについてはreferences/di-provider-scoping.mdを参照してください。

3. リクエストライフサイクル

NestJSリクエスト処理パイプラインを理解し尊重します：

Middleware → Guards → Interceptors (before) → Pipes → Route Handler → Interceptors (after) → Exception Filters

• Middleware: クロスカッティングコンサーン（ロギング、CORS、ボディパース）
• Guards: 認可および認証チェック（true/falseを返す）
• Interceptors: レスポンスデータの変換、キャッシング追加、タイミング測定
• Pipes: 入力パラメーターの検証と変換
• Exception Filters: エラーレスポンスのキャッチとフォーマット

4. エラーハンドリング

アプリケーション全体でエラーレスポンスを標準化します：

• HTTPに特化したエラーについてはHttpExceptionを拡張する
• ドメイン固有の例外クラス（例：OrderNotFoundException）を作成する
• 一貫したエラーフォーマットのためにグローバルExceptionFilterを実装する
• 予想されるビジネスロジック失敗にはResult パターンを使用する
• 例外を静かに飲み込まないこと

強制ルールについてはreferences/error-exception-filters.mdを参照してください。

5. 検証

API境界で入力検証を強制します：

• ValidationPipeをグローバルに有効化し、transform: trueとwhitelist: trueで設定する
• すべてのDTOプロパティをclass-validatorデコレーターで修飾する
• 型強制にはclass-transformerを使用する（@Type()、@Transform()）
• Create、Update、Response操作に対して別々のDTOを作成する
• ユーザー入力を信頼しない — すべてを検証する

強制ルールについてはreferences/api-validation-dto.mdを参照してください。

6. データベースパターン（Drizzle ORM）

NestJSプロバイダー慣例に従ってDrizzle ORMを統合します：

• Drizzleクライアントを注入可能なプロバイダーでラップする
• データアクセスカプセル化のためにRepository パターンを使用する
• ドメインモジュールごとのスキーマファイルでスキーマを定義する
• マルチステップ操作にはトランザクションを使用する
• データベースロジックをコントローラーから除外する

強制ルールについてはreferences/db-drizzle-patterns.mdを参照してください。

ベストプラクティス

領域	すること	しないこと
モジュール	ドメイン機能ごとに1モジュール	すべてをAppModuleに詰め込む
DIスコーピング	デフォルトはシングルトンスコープ	正当化なくREQUESTスコープを使用
エラーハンドリング	カスタム例外フィルター+ドメインエラー	素のtry/catchとconsole.log
検証	グローバルValidationPipe+DTOデコレーター	コントローラーの手動ifチェック
データベース	注入クライアントを使ったRepository パターン	コントローラーで直接DB クエリ
テスト	サービスのユニットテスト、コントローラーのe2eテスト	テストスキップまたは実装詳細テスト
構成	@nestjs/configと型付きスキーマ	ハードコード値またはprocess.envの使用

例

例：検証付き新規ドメインモジュール

「Product」機能を構築する場合、このワークフローに従います：

1. 適切なカプセル化でモジュールを作成します：

// product/product.module.ts
@Module({
  imports: [DatabaseModule],
  controllers: [ProductController],
  providers: [ProductService, ProductRepository],
  exports: [ProductService], // 他のモジュールが必要とするもののみエクスポート
})
export class ProductModule {}

2. 検証済みDTOを作成します：

// product/dto/create-product.dto.ts
import { IsString, IsNumber, IsPositive, MaxLength } from 'class-validator';

export class CreateProductDto {
  @IsString() @MaxLength(255) readonly name: string;
  @IsNumber() @IsPositive() readonly price: number;
}

3. エラーハンドリング付きサービス：

@Injectable()
export class ProductService {
  constructor(private readonly productRepository: ProductRepository) {}

  async findById(id: string): Promise<Product> {
    const product = await this.productRepository.findById(id);
    if (!product) throw new ProductNotFoundException(id);
    return product;
  }
}

4. モジュール登録を確認します：

# AppModuleにProductModuleが取り込まれていることを確認
grep -r "ProductModule" src/app.module.ts

# e2eを実行してエクスポートが機能していることを確認
npx jest --testPathPattern="product"

制約と警告

1. スコープを正当化なく混在させない — REQUESTスコープのプロバイダーはすべての依存先に連鎖する
2. コントローラーからデータベースに直接アクセスしない — 常にサービスとリポジトリレイヤーを経由する
3. forwardRef()を避ける — 循環依存関係を排除するためにモジュールをリストラクチャリングする
4. ValidationPipeをスキップしない — DTOを使ってAPI境界で常に検証する
5. シークレットをハードコードしない — 環境変数で@nestjs/configを使用する
6. モジュールを焦点化する — モジュールごとに1つのドメイン機能、「god modules」を避ける

参照

• references/architecture.md — NestJSアーキテクチャパターンの深掘り
• references/ — 正しい/誤った例を含む個別の強制ルール
• assets/templates/ — 一般的なNestJSコンポーネント用スターターテンプレート