NestJS開発パターン
モジュラーなTypeScriptバックエンドのための本番環境対応NestJSパターン。
アクティベーション条件
- NestJS APIやサービスの構築
- モジュール、コントローラー、プロバイダーの構造化
- DTOバリデーション、ガード、インターセプター、例外フィルターの追加
- 環境対応設定とデータベース統合の構成
- NestJSユニットテストやHTTPエンドポイントのテスト
プロジェクト構造
src/
├── app.module.ts
├── main.ts
├── common/
│ ├── filters/
│ ├── guards/
│ ├── interceptors/
│ └── pipes/
├── config/
│ ├── configuration.ts
│ └── validation.ts
├── modules/
│ ├── auth/
│ │ ├── auth.controller.ts
│ │ ├── auth.module.ts
│ │ ├── auth.service.ts
│ │ ├── dto/
│ │ ├── guards/
│ │ └── strategies/
│ └── users/
│ ├── dto/
│ ├── entities/
│ ├── users.controller.ts
│ ├── users.module.ts
│ └── users.service.ts
└── prisma/ または database/
- ドメインコードは機能モジュール内に配置する。
- 横断的フィルター、デコレーター、ガード、インターセプターは
common/に配置する。 - DTOはそれを所有するモジュールの近くに置く。
ブートストラップとグローバルバリデーション
async function bootstrap() {
const app = await NestFactory.create(AppModule, { bufferLogs: true });
app.useGlobalPipes(
new ValidationPipe({
whitelist: true,
forbidNonWhitelisted: true,
transform: true,
transformOptions: { enableImplicitConversion: true },
}),
);
app.useGlobalInterceptors(new ClassSerializerInterceptor(app.get(Reflector)));
app.useGlobalFilters(new HttpExceptionFilter());
await app.listen(process.env.PORT ?? 3000);
}
bootstrap();
- 公開APIでは常に
whitelistとforbidNonWhitelistedを有効にする。 - ルートごとにバリデーション設定を繰り返すのではなく、1つのグローバルバリデーションパイプを推奨する。
モジュール、コントローラー、プロバイダー
@Module({
controllers: [UsersController],
providers: [UsersService],
exports: [UsersService],
})
export class UsersModule {}
@Controller('users')
export class UsersController {
constructor(private readonly usersService: UsersService) {}
@Get(':id')
getById(@Param('id', ParseUUIDPipe) id: string) {
return this.usersService.getById(id);
}
@Post()
create(@Body() dto: CreateUserDto) {
return this.usersService.create(dto);
}
}
@Injectable()
export class UsersService {
constructor(private readonly usersRepo: UsersRepository) {}
async create(dto: CreateUserDto) {
return this.usersRepo.create(dto);
}
}
- コントローラーは薄く保つ：HTTP入力を解析し、プロバイダーを呼び出し、レスポンスDTOを返す。
- ビジネスロジックはコントローラーではなく、インジェクタブルなサービスに配置する。
- 他のモジュールが本当に必要とするプロバイダーのみをエクスポートする。
DTOとバリデーション
export class CreateUserDto {
@IsEmail()
email!: string;
@IsString()
@Length(2, 80)
name!: string;
@IsOptional()
@IsEnum(UserRole)
role?: UserRole;
}
- すべてのリクエストDTOを
class-validatorでバリデーションする。 - ORMエンティティを直接返すのではなく、専用のレスポンスDTOやシリアライザーを使用する。
- パスワードハッシュ、トークン、監査カラムなどの内部フィールドを漏洩させない。
認証、ガード、リクエストコンテキスト
@UseGuards(JwtAuthGuard, RolesGuard)
@Roles('admin')
@Get('admin/report')
getAdminReport(@Req() req: AuthenticatedRequest) {
return this.reportService.getForUser(req.user.id);
}
- 認証戦略とガードは、本当に共有されない限りモジュールローカルに保つ。
- 大まかなアクセスルールはガードでエンコードし、リソース固有の認可はサービスで行う。
- 認証済みリクエストオブジェクトには、明示的なリクエストタイプを推奨する。
例外フィルターとエラー形状
@Catch()
export class HttpExceptionFilter implements ExceptionFilter {
catch(exception: unknown, host: ArgumentsHost) {
const response = host.switchToHttp().getResponse<Response>();
const request = host.switchToHttp().getRequest<Request>();
if (exception instanceof HttpException) {
return response.status(exception.getStatus()).json({
path: request.url,
error: exception.getResponse(),
});
}
return response.status(500).json({
path: request.url,
error: 'Internal server error',
});
}
}
- API全体で一貫したエラーエンベロープを維持する。
- 想定されるクライアントエラーにはフレームワークの例外をスローし、予期しない障害は中央でログに記録してラップする。
設定と環境バリデーション
ConfigModule.forRoot({
isGlobal: true,
load: [configuration],
validate: validateEnv,
});
- 環境変数は最初のリクエストで遅延検証するのではなく、起動時に検証する。
- 設定へのアクセスは、型付きヘルパーまたは設定サービスの背後に保持する。
- dev/staging/prodの懸念事項は、機能コード全体で分岐するのではなく、設定ファクトリーで分割する。
永続化とトランザクション
- リポジトリ/ORMコードは、ドメイン言語を話すプロバイダーの背後に配置する。
- PrismaやTypeORMでは、トランザクションワークフローを、作業単位を所有するサービスで分離する。
- コントローラーが直接マルチステップの書き込みを調整しないようにする。
テスト
describe('UsersController', () => {
let app: INestApplication;
beforeAll(async () => {
const moduleRef = await Test.createTestingModule({
imports: [UsersModule],
}).compile();
app = moduleRef.createNestApplication();
app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
await app.init();
});
});
- プロバイダーは依存関係をモックして単体テストする。
- ガード、バリデーションパイプ、例外フィルターのリクエストレベルのテストを追加する。
- 本番環境で使用するのと同じグローバルパイプ/フィルターをテストでも再利用する。
本番環境のデフォルト設定
- 構造化ログとリクエスト相関IDを有効にする。
- 無効な環境変数/設定では、部分的に起動するのではなく終了する。
- DB/キャッシュクライアントには、明示的なヘルスチェック付きの非同期プロバイダー初期化を推奨する。
- バックグラウンドジョブとイベントコンシューマーは、HTTPコントローラー内ではなく、独自のモジュールに配置する。
- 公開エンドポイントでは、レート制限、認証、監査ログを明示的にする。