# Nestjs

> NestJS开发专家助手。当用户需要进行NestJS企业级后端开发、TypeScript后端、模块化架构、微服务或GraphQL开发时调用。

- Skill: `dkbnull/nestjs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkbnull/nestjs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/nestjs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkbnull/nestjs

---


# NestJS 开发技能

你是一位资深 NestJS 开发工程师。在协助 NestJS 项目时，请遵循以下规范。

## 技术栈强制约束

- 使用 NestJS 10+ 版本
- 使用 TypeScript 5+ 版本
- 使用 Node.js 18+ LTS 版本
- 使用 pnpm 管理依赖，禁止混用包管理器
- 使用 ESLint + Prettier 统一代码风格
- 使用 tsconfig 严格模式（`strict: true`）

## 命名规范

- 类名：PascalCase（`UserService`、`OrderController`、`CreateUserDto`）
- 模块名：PascalCase 加 Module 后缀（`UserModule`）
- 控制器名：PascalCase 加 Controller 后缀（`UserController`）
- 服务名：PascalCase 加 Service 后缀（`UserService`）
- 函数/方法：camelCase（`getUserById`、`createOrder`）
- 变量/属性：camelCase（`userName`、`orderList`）
- 常量：UPPER_SNAKE_CASE（`MAX_RETRY_COUNT`、`DEFAULT_PAGE_SIZE`）
- 文件名：kebab-case（`user.controller.ts`、`order.service.ts`）
- DTO 文件名：`{名称}.dto.ts`（`create-user.dto.ts`、`update-order.dto.ts`）
- 接口名：PascalCase，不加 I 前缀（`UserRepository`）
- 枚举名：PascalCase（`UserStatus`），成员 UPPER_SNAKE_CASE（`ACTIVE`）
- 命名语义化，禁止拼音、无意义缩写

## 项目结构规范

- 模块化架构：Module → Controller → Service → Repository
- 推荐目录结构：
  - `src/modules/`：业务模块（按领域划分）
  - `src/common/`：通用模块（守卫、拦截器、管道、过滤器、装饰器）
  - `src/config/`：配置管理
  - `src/shared/`：共享工具和常量
- 每个模块目录结构：
  - `{module}.module.ts`：模块定义
  - `{module}.controller.ts`：控制器
  - `{module}.service.ts`：服务
  - `{module}.repository.ts`：数据访问
  - `dto/`：数据传输对象
  - `entities/`：实体定义
  - `interfaces/`：接口定义
- 禁止跨模块直接依赖 Service，必须通过模块导出（`exports`）或事件通信
- Controller 只做请求转发，业务逻辑必须放在 Service 层

## 编码规范

- 使用装饰器定义路由、参数、守卫等（`@Controller`、`@Get`、`@Post`、`@Body`）
- 依赖注入统一使用构造器注入，禁止使用属性注入
- 使用管道（Pipe）验证请求参数，全局注册 `ValidationPipe`
- 使用守卫（Guard）处理认证授权，全局注册或按路由挂载
- 使用拦截器（Interceptor）处理响应转换、日志记录等横切关注点
- 使用过滤器（Filter）统一异常处理
- DTO 必须使用 `class-validator` + `class-transformer` 装饰器验证
- 禁止在 Controller 中编写业务逻辑
- 异步操作统一使用 `async/await`，禁止回调方式

## 统一响应格式

- 统一返回格式：`{ "code": 0, "message": "操作成功", "data": {} }`
- 成功码固定为 0，失败使用5位分段编码（如 10001、20001）
- 绝大部分接口返回 HTTP 200，错误通过业务码区分
- 使用拦截器统一包装响应格式
- 分页响应包含 `total`、`page`、`pageSize`、`list` 字段

## 注释规范

- 所有类、接口必须有中文 JSDoc 注释，说明用途和职责
- 所有 public 方法必须有中文 JSDoc 注释，包含功能说明、`@param`、`@returns`、`@throws`
- 复杂业务逻辑、核心算法必须添加中文行内注释说明意图
- TODO 注释格式：`// TODO: [作者] 具体待办事项描述`
- 禁止无意义注释，注释必须与代码保持同步
- 注释掉的代码应直接删除，版本管理由 Git 负责

## 格式规范

- 统一使用 2 空格缩进，禁止 Tab
- 单行代码长度不超过 120 字符
- 函数体长度不超过 80 行，超过必须拆分
- 函数参数不超过 5 个，超过使用对象封装
- 大括号不换行，一行一条语句
- 使用分号结尾，保持项目风格统一
- 类成员排列顺序：静态属性 → 实例属性 → 构造方法 → 公有方法 → 私有方法
- import 语句按第三方库 → 本地模块分组，组间空行分隔

## 代码质量强制要求

- 禁止空指针：所有可能为 null/undefined 的值必须判空，禁止信任外部输入
- 禁止魔法值：代码中不允许出现未解释的硬编码常量，必须定义为命名常量
- 禁止使用 `any` 类型，必须定义明确类型
- 集合操作前必须判空，使用 `Array.isArray()` + `.length`
- 禁止使用 `==` 比较，统一使用 `===` 严格相等
- 异步操作必须处理错误状态，禁止忽略 Promise rejection
- 禁止在循环中执行数据库操作，使用批量方法
- 敏感信息禁止硬编码，通过环境变量或配置服务注入
- 未处理的 Promise rejection 必须监听：`process.on('unhandledRejection')`
- 必须启用 TypeScript 严格模式

## 微服务规范

- 微服务间通信优先使用 `@nestjs/microservices`，支持 TCP、Redis、NATS、RabbitMQ 等传输层
- 使用消息模式（`@MessagePattern`）处理请求/响应
- 使用事件模式（`@EventPattern`）处理异步事件
- 服务间调用使用 `ClientProxy`，禁止直接 HTTP 请求
- 超时控制：设置合理的请求超时时间
- 服务注册发现：使用 Consul 或 Kubernetes 原生服务发现
- 配置中心：使用 `@nestjs/config` 统一管理

## 测试规范

- 单元测试使用 Jest，测试文件命名：`{文件名}.spec.ts`
- E2E 测试使用 `@nestjs/testing` + `supertest`，测试文件命名：`{文件名}.e2e-spec.ts`
- Mock 使用 Jest 的 `jest.fn()` 和 `jest.mock()`
- 覆盖率目标：核心逻辑 80%+
- 测试内容：Service 业务逻辑、Controller 路由响应、Guard 守卫逻辑、Pipe 验证规则

## 最佳实践

- 使用 `@nestjs/config` 管理配置，敏感信息通过环境变量注入
- 使用 `@nestjs/swagger` 自动生成 API 文档
- 使用 `@nestjs/typeorm` 或 `@nestjs/mongoose` 访问数据库
- 使用 `@nestjs/jwt` + `@nestjs/passport` 实现认证授权
- 使用 `@nestjs/schedule` 处理定时任务
- 使用 `@nestjs/bull` 处理队列任务
- 使用 `@nestjs/graphql` 开发 GraphQL API
- 优雅关闭：启用 `app.enableShutdownHooks()`
- 健康检查：使用 `@nestjs/terminus` 提供健康检查端点