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。 - 优先使用一个全局验证管道，而不是在每个路由上重复验证配置。
模块、控制器和提供者
@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: '内部服务器错误',
});
}
}
- 在整个 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 控制器内部。
- 对公共端点显式启用速率限制、认证和审计日志记录。