nestjs-best-practices

NestJS 最佳实践

构建可用于生产环境的 NestJS 应用的综合指南。包含 13 个类别中的 26 条规则，涵盖安全、架构、性能、验证、数据库操作、身份验证和高级模式。

适用场景

在以下情况下参考这些指南：

• 编写新的 NestJS 模块、控制器或服务
• 实现身份验证和授权
• 设置 Prisma 数据库操作
• 创建 DTO 和验证管道
• 添加中间件或守卫
• 实现错误处理和日志记录
• 按照最佳实践审查 NestJS 代码
• 重构现有 NestJS 应用

按优先级划分的规则类别

优先级	类别	影响	前缀
1	安全	严重	security-
2	性能	高	performance-
3	架构	高	architecture-
4	错误处理	高	error-handling-
5	验证	严重	validation-
6	数据库	严重	database-
7	身份验证	严重	auth-
8	API	中	api-
9	配置	严重	config-
10	测试	中	testing-
11	部署	中	deployment-
12	中间件	中	middleware-
13	高级	高	advanced-

快速参考

1. 安全（严重）

• security-cors-whitelist - 仅启用允许列表中的来源进行 CORS
• security-dependency-audit - 定期使用 bun 进行依赖项安全审计
• security-helmet-headers - 使用 Helmet 中间件设置安全标头

2. 性能（高）

• performance-redis-caching - 使用 Redis 缓存常用数据

3. 架构（高）

• architecture-short-functions - 保持函数简短且职责单一
• architecture-feature-modules - 按功能模块组织代码
• architecture-no-dead-code - 移除未使用的代码和依赖项
• architecture-thin-controllers - 遵循单一职责原则，将控制器与服务分离
• architecture-naming-conventions - 使用一致的命名约定
• architecture-event-driven - 使用事件驱动架构实现松耦合

4. 错误处理（高）

• error-handling-exception-filter - 启用全局异常过滤器
• error-handling-structured-logging - 实施适当的日志记录策略

5. 验证（严重）

• validation-custom-pipes - 创建自定义管道来转换查询参数
• validation-dto-validation - 使用 DTO 和 ValidationPipe 验证所有输入

6. 数据库（严重）

• database-parameterized-queries - 使用参数化查询防止 SQL 注入（Prisma v7）

7. 身份验证（严重）

• auth-password-hashing - 使用 Bun 内置的 Crypto 安全地哈希密码（argon2/bcrypt）
• auth-route-guards - 使用守卫保护路由

8. API（中）

• api-cursor-pagination - 对大型数据集使用基于游标的分页
• api-swagger-docs - 生成 Swagger/OpenAPI 文档

9. 配置（严重）

• config-no-secrets - 切勿将机密信息硬编码，改用环境变量

10. 测试（中）

• testing-unit-tests - 编写全面的单元测试

11. 部署（中）

• deployment-health-checks - 实现健康检查端点

12. 中间件（中）

• middleware-compression - 启用压缩中间件以压缩响应
• middleware-rate-limiting - 为所有路由实现速率限制

13. 高级（高）

• advanced-lazy-loading - 延迟加载非关键模块
• advanced-scheduled-tasks - 使用 @nestjs/schedule 执行 cron 作业和计划任务

如何使用

阅读各个规则文件，了解详细说明和代码示例：

rules/security-cors-whitelist.md
rules/auth-route-guards.md
rules/validation-dto-validation.md
rules/_sections.md

每个规则文件都包含：

• “For AI Agents”部分，提供分步实施说明
• 用于代码审查的快速参考清单
• ❌ 错误与 ✅ 正确模式，以及文件位置
• 使用 bun add 的安装命令
• NestJS + Prisma 的全面代码示例
• 安全与性能注意事项

关键模式

便于 Agent 使用的格式

所有规则都针对 AI Agent 进行了优化，包含：

• 明确的文件位置（例如，src/users/users.service.ts）
• 分步的“For AI Agents”部分
• ✅ 正确与 ❌ 错误模式对比
• 快速参考清单
• 清晰的安装说明

技术栈

• 框架：NestJS 和 Express/Fastify 适配器
• 运行时：Bun（原生加密、调度功能）
• 数据库：Prisma v7（sql 模板标签、交互式事务）
• 验证：class-validator + class-transformer
• 安全：Helmet、CORS 白名单、速率限制
• 调度：@nestjs/schedule，使用 cron/interval 装饰器
• 事件：EventEmitter2，实现松散耦合

完整编译文档

如需查看包含所有展开规则的完整指南：AGENTS.md

构建命令

cd packages/nestjs-best-practices-build
bun install
bun run build      # Generate AGENTS.md
bun run validate   # Validate rule files
bun run dev        # Build and validate

统计数据

• 13 个章节，涵盖 NestJS 开发的各个方面
• 26 条规则，按影响程度划分优先级（CRITICAL、HIGH、MEDIUM）
• 兼容 Prisma v7 的数据库模式
• Bun 运行时原生功能（Crypto.hashPassword、@nestjs/schedule）
• 针对自动代码生成与审查优化的 Agent