nestjs-code-review

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. 依存性注入のレビュー：注入可能なすべてのサービスがコンストラクターインジェクションを使用していることを検証します。プロバイダーのスコープ（シングルトン、リクエスト、トランジェント）が意図したライフサイクルと一致していることを確認します。DI コンテナーを迂回する直接インスタンス化がないことを確認します。

4. コントローラーの評価：HTTP メソッドの使い方、ルートの命名、ステータスコード、リクエスト／レスポンス DTO、バリデーションパイプ、OpenAPI デコレーターをレビューします。コントローラーが薄く保たれていることを確認します。ビジネスロジックはサービスに置くべきです。

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

6. セキュリティの確認：ガードの実装、認証／認可のパターン、class-validator による入力検証、一般的な脆弱性（インジェクション、XSS、CSRF）への対策をレビューします。

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

8. 指摘事項の検証（必須チェックポイント）：最終化する前に、Critical と Warning の各指摘事項について、再現可能な根拠（ファイルパス、行番号、正確なコードスニペット）と具体的で実行可能な修正方法があることを確認します。スタイル上の好み、主観が強すぎるもの、具体的な修正方法がない指摘事項は削除するか、重要度を引き下げます。

9. レビューレポートの作成：重大度別（Critical、Warning、Suggestion）の指摘事項、肯定的な所見、コード例を含む優先順位付きの推奨事項をまとめた構造化レポートを作成します。

例

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

// ❌ Bad: Fat controller with business logic and missing validation
@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);
  }
}

// ✅ Good: Thin controller with proper DTOs, validation, and service delegation
@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：依存性注入のレビュー

// ❌ Bad: Direct instantiation bypasses 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');
  }
}

// ✅ Good: Proper constructor injection
@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：エラー処理のレビュー

// ❌ Bad: Generic error handling with information leakage
@Get(':id')
async findOne(@Param('id') id: string) {
  try {
    return await this.service.findOne(id);
  } catch (error) {
    throw new HttpException(error.message, 500);
  }
}

// ✅ Good: Domain-specific exceptions with proper HTTP mapping
@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：ガードの実装のレビュー

// ❌ Bad: Authorization logic in controller
@Get('admin/dashboard')
async getDashboard(@Req() req: Request) {
  if (req.user.role !== 'admin') {
    throw new ForbiddenException();
  }
  return this.dashboardService.getData();
}

// ✅ Good: Guard-based authorization with decorator
@Get('admin/dashboard')
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles(Role.ADMIN)
async getDashboard(): Promise<DashboardDto> {
  return this.dashboardService.getData();
}

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

// ❌ Bad: Monolithic module with everything
@Module({
  imports: [TypeOrmModule.forFeature([User, Order, Product, Review])],
  controllers: [UserController, OrderController, ProductController],
  providers: [UserService, OrderService, ProductService, ReviewService],
})
export class AppModule {}

// ✅ Good: Feature-based module organization
@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. 重大な問題（必ず修正）

セキュリティ脆弱性、データ破損、本番環境での障害につながる可能性がある問題です。

3. 警告（修正を推奨）

ベストプラクティスに反する、保守性を損なう、またはバグにつながる可能性がある問題です。

4. 提案（改善を検討）

コードの可読性、パフォーマンス、開発者体験の改善点です。

5. 肯定的な所見

評価し、推奨すべき適切な実装パターンや優れた実践です。

6. 推奨事項

特に効果の大きい改善について、コード例を含む優先順位付きの次のステップです。

ベストプラクティス

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

制約と警告

• 単一の ORM を強制しないでください。コードベースでは TypeORM、Prisma、Drizzle、MikroORM のいずれかが使われている可能性があります
• NestJS のデフォルトと異なる場合でも、既存のプロジェクト規約を尊重します
• 確信度の高い問題に焦点を当て、スタイル上の好みに関する誤検知を避けます
• マイクロサービスのパターンをレビューする際は、トランスポート層固有の制約を考慮します
• 重大な問題がない限り、アーキテクチャの書き換えを提案しないでください

参考資料

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

• references/patterns.md — 例を含む NestJS のベストプラクティスパターン
• references/anti-patterns.md — レビューで指摘すべき、NestJS の一般的なアンチパターン
• references/checklist.md — 分野別に整理された、包括的なレビュー用チェックリスト