nestjs-patterns

name nestjs-patterns description NestJS 架构模式，涵盖模块、控制器、提供者、DTO 验证、守卫、拦截器、配置以及生产级 TypeScript 后端。 origin ECC 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/ or 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 。 优先使用一个全局验证管道，而不是为每个路由重复验证配置。 模块、控制器和提供者 @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 ; } 使用 class-validator 验证每个请求 DTO。 使用专用的响应 DTO 或序列化器，而不是直接返回 ORM 实体。 避免泄露内部字段，如密码哈希、令牌或审计列。 认证、守卫与请求上下文 @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, }); 在启动时验证环境变量，而不是在首次请求时惰性验证。 将配置访问限制在类型化辅助函数或配置服务之后。 在配置工厂中拆分开发/预发布/生产关注点，而不是在功能代码中到处分支。 持久化与事务 将仓库/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。 在环境/配置无效时终止，而不是部分启动。 优先使用异步提供者初始化数据库/缓存客户端，并附带显式健康检查。 将后台任务和事件消费者放在自己的模块中，而不是 HTTP 控制器内。 对公共端点明确启用速率限制、认证和审计日志。