nestjs-best-practices

NestJS 11 のベストプラクティス

クイックリファレンス

トピック	使用する場面	リファレンス
コアアーキテクチャ	モジュール、プロバイダー、DI、forwardRef、カスタムデコレーター	core-architecture.md
リクエストのライフサイクル	ミドルウェア、ガード、インターセプター、パイプ、フィルター	request-lifecycle.md
バリデーションとパイプ	DTO、class-validator、ValidationPipe、変換	validation-pipes.md
認証	JWT、Passport、ガード、ローカル／OAuth 戦略、RBAC	authentication.md
データベース	TypeORM、Prisma、Drizzle ORM、リポジトリパターン	database-integration.md
テスト	単体テスト、E2E テスト、プロバイダーのモック	testing.md
OpenAPI と GraphQL	Swagger デコレーター、リゾルバー、サブスクリプション	openapi-graphql.md
マイクロサービス	TCP、Redis、NATS、Kafka のパターン	microservices.md

基本パターン

プロバイダーを含むモジュール

@Module({
  imports: [DatabaseModule],
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService], // Export for other modules
})
export class UsersModule {}

バリデーションを行うコントローラー

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Post()
  create(@Body() createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto);
  }

  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {
    return this.usersService.findOne(id);
  }
}

バリデーション付き DTO

import { IsEmail, IsString, MinLength, IsOptional } from 'class-validator';

export class CreateUserDto {
  @IsEmail()
  email: string;

  @IsString()
  @MinLength(8)
  password: string;

  @IsOptional()
  @IsString()
  name?: string;
}

例外フィルター

@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const status = exception.getStatus();

    response.status(status).json({
      statusCode: status,
      message: exception.message,
      timestamp: new Date().toISOString(),
    });
  }
}

JWT を使うガード

@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
  canActivate(context: ExecutionContext) {
    return super.canActivate(context);
  }
}

NestJS 11 の破壊的変更

• Express v5：ワイルドカードには名前が必要です（例：*splat）。オプションのパラメーターには波括弧を使います /:file{.:ext}
• Node.js 20+：必要な最小バージョンです
• Fastify v5：Fastify ユーザー向けのアダプターが更新されました
• 動的モジュール：同一の設定で同じモジュールを複数回インポートすると、別々のインスタンスになります

よくある間違い

1. 循環依存で forwardRef() を使わない - 「cannot resolve dependency」エラーが発生します。forwardRef(() => ModuleName) でラップしてください
2. HttpException ではなく通常のエラーをスローする - ステータスコードが失われ、例外フィルターが機能しなくなります。throw new BadRequestException('message') を使ってください
3. @Injectable() デコレーターがない - プロバイダーを注入できません。サービスには必ずデコレーターを付けてください
4. whitelist: true を指定せずにグローバル ValidationPipe を使う - 想定外のプロパティが許可されます。whitelist: true, forbidNonWhitelisted: true を設定してください
5. プロバイダーをエクスポートせずにモジュールをインポートする - モジュール間でプロバイダーを共有するには exports 配列を使ってください
6. ConfigModule.forRoot() を使わずに非同期設定を行う - ConfigService が未定義になります。AppModule に ConfigModule をインポートしてください
7. overrideProvider() を使わずにテストする - 単体テストで実際のサービスが使われます。overrideProvider(Service).useValue(mock) で依存関係をモックしてください
8. E2E テスト間でデータベースの状態を共有する - テスト間で分離されません。トランザクションを使うか、beforeEach でテーブルを空にしてください