构建 NestJS 企业级 TypeScript 后端时…

在 NestJS 项目中编写 module/controller/service/DTO、配置依赖注入、加 Guard 认证与 Swagger 文档、并补齐单元与 E2E 测试时使用。

适用场景

解决思路

1. 先分析需求：列出需要哪些 module、endpoint、entity 以及实体之间的关系。
2. 设计结构：规划模块划分方式与模块之间的依赖关系。
3. 实现：创建 module、service、controller，并正确接线依赖注入。
4. 加固安全：加上 guard、校验 pipe 和认证逻辑。
5. 验证：运行 `npm run lint`、`npm run test`，并用 `nest info` 确认 DI 依赖图正确。
6. 测试：为 service 写单元测试，为 controller 写 E2E 测试。
7. 按上下文加载对应参考文档：controllers-routing.md（controller/路由/Swagger）、services-di.md（service/DI/provider）、dtos-validation.md（校验/class-validator/DTO）、authentication.md（JWT/Passport/guard/授权）、testing-patterns.md（单元与 E2E 测试、mock）、migration-from-express.md（从 Express.js 迁移）。
8. 所有 service 使用 `@Injectable()` 与构造函数注入，绝不用 `new` 手动实例化 service。
9. 在 DTO 上用 `class-validator` 装饰器（如 `@IsEmail`、`@IsString`、`@MinLength`）校验所有输入，并全局启用 `ValidationPipe`。
10. 所有请求/响应体都使用 DTO，绝不把原始 `req.body` 直接传给 service。
11. 在 service 中抛出类型化的 HTTP 异常（`NotFoundException`、`ConflictException` 等），而不是返回裸错误。
12. 用 `@ApiTags`、`@ApiOperation` 和响应装饰器（如 `@ApiCreatedResponse`）为所有端点写文档。
13. 为每个 service 方法用 `Test.createTestingModule` 编写单元测试；测试中通过 `getRepositoryToken(User)` + `useValue` 注入 mock 仓库，并在 `beforeEach` 中调用 `jest.clearAllMocks()`。
14. 所有配置值通过 `ConfigModule` 和 `process.env` 读取，绝不硬编码。
15. 在 module 中仅当其他模块需要该 service 时才写 `exports`。
16. 实现一个功能时按固定顺序产出：`.module.ts` → `.controller.ts`（含 Swagger 装饰器）→ `.service.ts`（含类型化错误处理）→ `dto/*.dto.ts`（含 `class-validator` 装饰器）→ `*.service.spec.ts` 单元测试。
17. 不要在响应中暴露密码、密钥或内部堆栈信息。
18. 不要接受未校验的用户输入，始终应用 `ValidationPipe`。
19. 除非绝对必要且已记录，不要使用 `any` 类型。
20. 不要在模块之间制造循环依赖，`forwardRef()` 只能作为最后手段。
21. 不要在源码中硬编码主机名、端口或凭据。
22. 不要跳过 service 方法中的错误处理。

适用边界 · 注意事项

• 非 NestJS 项目（纯 Express、Koa、Fastify 等）不适用，除非正在做 Express → NestJS 迁移。
• 一次性脚本或不需要模块化与依赖注入的极简服务，套用这套分层结构属于过度设计。