NestJS コードレビュー

概要

NestJS アプリケーション向けの構造化されたコードレビューを提供します。検出結果は重大度別（Critical、Warning、Suggestion）に分類され、実行可能な推奨事項が含まれます。詳細な分析は nestjs-code-review-expert エージェントに委譲されます。

使用場面

• 「NestJS コードをレビューしてほしい」「NestJS コードレビューしてください」「NestJS のコントローラー/サービスをチェックしてほしい」
• プルリクエストのマージ前または新機能実装後
• NestJS デコレーター、DI パターン、ガード実装の検証
• NestJS モジュールとプロバイダーのアーキテクチャ検証
• DTO、パイプ、インターセプター、データベース統合（TypeORM、Prisma、Drizzle）のレビュー

手順

1. スコープの特定: レビュー対象となる NestJS ファイルとモジュールを決定します。glob と grep を使用して、対象領域内のコントローラー、サービス、モジュール、ガード、インターセプター、パイプを発見します。

2. モジュール構造を分析: 適切なモジュール構成を確認します。各機能は明確に定義されたインポート、コントローラー、プロバイダー、エクスポートを持つ独自のモジュールを備えている必要があります。循環依存関係と適切なモジュール境界をチェックします。

3. 依存性注入をレビュー: すべてのインジェクタブルサービスがコンストラクタインジェクションを使用していることを検証します。プロバイダーのスコープ（singleton、request、transient）が意図されたライフサイクルと一致することを確認します。DI コンテナーをバイパスする直接インスタンス化がないことを確認します。

4. コントローラーを評価: HTTP メソッドの使用法、ルート命名、ステータスコード、リクエスト/レスポンス DTO、検証パイプ、OpenAPI デコレーターをレビューします。コントローラーが薄いことを確認します。ビジネスロジックはサービスに属します。

5. サービスとビジネスロジックを評価: サービスがビジネスロジックを適切にカプセル化していることをチェックします。エラーハンドリング、トランザクション管理、インフラストラクチャの関心事からの適切な分離を検証します。メソッドが大きすぎたり責任が多すぎたりするサービスを探します。

6. セキュリティをチェック: ガード実装、認証/認可パターン、class-validator による入力検証、一般的な脆弱性（インジェクション、XSS、CSRF）からの保護をレビューします。

7. テストをレビュー: コントローラー、サービス、ガード、パイプのテストカバレッジを評価します。適切なモッキング戦略と、テストが実装の詳細ではなく動作を検証していることを確認します。

8. 検出結果を検証（必須チェックポイント）: 最終化する前に、各 Critical および Warning の検出結果に再現可能な証拠（ファイルパス、行番号、正確なコードスニペット）と具体的で実行可能な修正があることを確認します。スタイル設定、過度に主観的、または具体的な改善策がない検出結果を削除またはダウングレードします。

9. レビューレポートを作成: 重大度別に分類された検出結果（Critical、Warning、Suggestion）、肯定的な観察、および優先順位付けされた推奨事項（コード例付き）を含む構造化レポートを生成します。

例

例 1: コントローラーのレビュー

// ❌ 悪い例: ビジネスロジックを含む太いコントローラーと検証の欠落
@Controller('users')
export class UserController {
  constructor(private readonly userRepo: Repository<User>) {}

  @Post()
  async create(@Body() body: any) {
    const user = this.userRepo.create(body);
    return this.userRepo.save(user);
  }
}

// ✅ 良い例: 適切な DTO、検証、サービス委譲を備えた薄いコントローラー
@Controller('users')
@ApiTags('Users')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post()
  @HttpCode(HttpStatus.CREATED)
  @ApiOperation({ summary: 'Create a new user' })
  @ApiResponse({ status: 201, type: UserResponseDto })
  async create(
    @Body(ValidationPipe) createUserDto: CreateUserDto,
  ): Promise<UserResponseDto> {
    return this.userService.create(createUserDto);
  }
}

例 2: 依存性注入のレビュー

// ❌ 悪い例: DI をバイパスする直接インスタンス化
@Injectable()
export class OrderService {
  private readonly logger = new Logger();
  private readonly emailService = new EmailService();

  async createOrder(dto: CreateOrderDto) {
    this.emailService.send(dto.email, 'Order created');
  }
}

// ✅ 良い例: 適切なコンストラクタインジェクション
@Injectable()
export class OrderService {
  private readonly logger = new Logger(OrderService.name);

  constructor(
    private readonly orderRepository: OrderRepository,
    private readonly emailService: EmailService,
  ) {}

  async createOrder(dto: CreateOrderDto): Promise<Order> {
    const order = await this.orderRepository.create(dto);
    await this.emailService.send(dto.email, 'Order created');
    return order;
  }
}

例 3: エラーハンドリングのレビュー

// ❌ 悪い例: 情報漏洩を伴う汎用的なエラーハンドリング
@Get(':id')
async findOne(@Param('id') id: string) {
  try {
    return await this.service.findOne(id);
  } catch (error) {
    throw new HttpException(error.message, 500);
  }
}

// ✅ 良い例: 適切な HTTP マッピングを備えたドメイン固有の例外
@Get(':id')
async findOne(@Param('id', ParseUUIDPipe) id: string): Promise<UserResponseDto> {
  const user = await this.userService.findOne(id);
  if (!user) {
    throw new NotFoundException(`User with ID ${id} not found`);
  }
  return user;
}

例 4: ガード実装のレビュー

// ❌ 悪い例: コントローラーに認可ロジックがある
@Get('admin/dashboard')
async getDashboard(@Req() req: Request) {
  if (req.user.role !== 'admin') {
    throw new ForbiddenException();
  }
  return this.dashboardService.getData();
}

// ✅ 良い例: デコレーターを備えたガードベースの認可
@Get('admin/dashboard')
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles(Role.ADMIN)
async getDashboard(): Promise<DashboardDto> {
  return this.dashboardService.getData();
}

例 5: モジュール構成のレビュー

// ❌ 悪い例: すべてを含むモノリシックモジュール
@Module({
  imports: [TypeOrmModule.forFeature([User, Order, Product, Review])],
  controllers: [UserController, OrderController, ProductController],
  providers: [UserService, OrderService, ProductService, ReviewService],
})
export class AppModule {}

// ✅ 良い例: 機能ベースのモジュール構成
@Module({
  imports: [UserModule, OrderModule, ProductModule],
})
export class AppModule {}

@Module({
  imports: [TypeOrmModule.forFeature([User])],
  controllers: [UserController],
  providers: [UserService, UserRepository],
  exports: [UserService],
})
export class UserModule {}

レビュー出力形式

すべてのコードレビュー検出結果を以下のように構造化します：

1. 概要

簡潔な概要、総合品質スコア（1～10）、および主な観察。

2. Critical（必須修正）

セキュリティ脆弱性、データ破損、本番環境の障害を引き起こす可能性がある問題。

3. Warning（修正推奨）

ベストプラクティスに違反し、保守性を低下させ、バグにつながる可能性がある問題。

4. Suggestion（改善検討）

コード可読性、パフォーマンス、開発者体験を向上させるための改善提案。

5. 肯定的な観察

実装の良いパターンと良好なプラクティスの指摘と奨励。

6. 推奨事項

最大の影響を持つ改善に関するコード例を含む優先順位付けされた次のステップ。

ベストプラクティス

• コントローラーは薄くして、すべてのビジネスロジックをサービスに委譲する
• すべてのリクエスト/レスポンスペイロードに対して class-validator を備えた DTO を使用する
• パラメーター検証のために ParseUUIDPipe、ParseIntPipe などを適用する
• HttpException を拡張するドメイン固有の例外クラスを使用する
• 明確な境界とエクスポートを備えた機能モジュールにコードを構成する
• コンストラクタインジェクションを推奨し、インジェクタブルサービス用に new を使用しない
• インラインチェックではなく、認証と認可にはガードを適用する
• 横断的関心事（ログ、キャッシュ、変換）にはインターセプターを使用する
• すべてのエンドポイントに OpenAPI デコレーター（@ApiTags、@ApiOperation、@ApiResponse）を追加する
• サービスのユニットテストとコントローラーの統合テストを作成する

制約と警告

• 単一の ORM を強制しないでください。コードベースは TypeORM、Prisma、Drizzle、または MikroORM を使用する場合があります
• NestJS のデフォルトと異なる場合でも、既存のプロジェクト規約を尊重する
• 高信頼度の問題に焦点を当ててください。スタイル設定に関する偽陽性を避ける
• マイクロサービスパターンをレビューする場合、トランスポート層固有の制約を考慮する
• Critical の問題が保証されない限り、アーキテクチャの完全な書き直しを提案しない

参考資料

詳細なレビューチェックリストとパターンドキュメントについては、references/ ディレクトリを参照してください：

• references/patterns.md — 例を含む NestJS ベストプラクティスパターン
• references/anti-patterns.md — レビュー中にフラグを立てる一般的な NestJS アンチパターン
• references/checklist.md — 領域別に整理された包括的なレビューチェックリスト