nestjs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<EXTREMELY-IMPORTANT> This skill is a routing shell over the NestJS reference set.

Non-negotiable rules:

Read
```
references/stack.md
```
first to understand the project's NestJS version, ORM, and locked decisions.
Then load only the references needed for the actual task.
One module per domain — controllers, services, DTOs, and entities live together in their module directory.
Controllers are thin — validate (DTO + pipe), delegate (service), return. No business logic.
All input validated via DTOs — class-validator decorators on every DTO,
```
ValidationPipe
```
globally.
Dependency injection everywhere — never
```
new Service()
```
. Inject via constructor, provide via module.
No circular dependencies — use
```
forwardRef()
```
only as a last resort, prefer restructuring.
Keep the heavy NestJS guidance in
references/
, not inline here.

</EXTREMELY-IMPORTANT>

<EXTREMELY-IMPORTANT> 本技能是基于NestJS参考集的路由外壳。

不可协商的规则：

首先阅读
```
references/stack.md
```
，了解项目的NestJS版本、ORM以及已确定的决策。
仅加载实际任务所需的参考内容。
每个领域对应一个模块——控制器、服务、DTO和实体都存放在各自的模块目录中。
控制器要轻量化——验证（DTO + 管道）、委托（服务）、返回结果。不包含业务逻辑。
所有输入均通过DTO验证——每个DTO都使用class-validator装饰器，全局启用
```
ValidationPipe
```
。
全程使用依赖注入——绝对不要使用
```
new Service()
```
。通过构造函数注入，通过模块提供。
禁止循环依赖——仅在万不得已时使用
```
forwardRef()
```
，优先重构代码。
将复杂的NestJS指导内容放在
references/
目录中，不要内联在此处。

</EXTREMELY-IMPORTANT>

nestjs

Inputs

输入项

```
$request
```
: The NestJS module, endpoint, subsystem, or feature being worked on

```
$request
```
: 正在开发的NestJS模块、端点、子系统或功能

Goal

目标

Route NestJS work through the project's module-based architecture so implementation follows the established patterns for dependency injection, validation, data access, and request lifecycle.

通过项目的模块化架构规划NestJS开发工作，确保实现过程符合依赖注入、验证、数据访问和请求生命周期的既定模式。

Step 0: Read the stack contract

步骤0：阅读栈合约

Always start with:

```
references/stack.md
```

That establishes: NestJS version, ORM (TypeORM/Prisma/Drizzle), package manager, auth strategy, queue system, and locked dependency choices.

Success criteria: The project's NestJS architecture and locked decisions are explicit before implementation starts.

始终从以下内容开始：

```
references/stack.md
```

该文件确定了：NestJS版本、ORM（TypeORM/Prisma/Drizzle）、包管理器、认证策略、队列系统以及已锁定的依赖选择。

成功标准：在开始实现前，明确项目的NestJS架构和已确定的决策。

Step 1: Load only the relevant references

步骤1：仅加载相关参考内容

Use the routing table to pick reference files. Do not bulk-load the full reference tree.

Task	Read
NestJS version, ORM, key deps, CLI, project layout	`references/stack.md`
Folder conventions, module organization, barrel exports	`references/project-structure.md`
Creating or editing a module	`references/modules.md`
Controllers, route decorators, request lifecycle	`references/controllers.md`
Services, providers, dependency injection	`references/providers.md`
DTOs, class-validator, ValidationPipe, transformation	`references/validation.md`
TypeORM entities, repositories, migrations	`references/typeorm.md`
Prisma integration with NestJS	`references/prisma.md`
Guards, authentication, authorization, JWT, Passport	`references/auth.md`
Interceptors, logging, caching, response mapping	`references/interceptors.md`
Pipes, custom validation, parameter transformation	`references/pipes.md`
Exception filters, custom exceptions, error responses	`references/error-handling.md`
BullMQ queues, processors, flows	`references/queues.md`
WebSocket gateways, events, rooms	`references/websockets.md`
Microservices, transports, message patterns	`references/microservices.md`
OpenAPI/Swagger decorators, schema generation	`references/openapi.md`
Unit tests, e2e tests, testing module, mocking	`references/testing.md`
Configuration, ConfigModule, env validation	`references/config.md`
Middleware, lifecycle hooks, shutdown	`references/middleware.md`
Logging with pino or built-in logger	`references/logging.md`
Health checks, Terminus	`references/health.md`
CQRS, events, sagas	`references/cqrs.md`
Scheduling, cron jobs, intervals	`references/scheduling.md`
Docker, deployment, production setup	`references/docker.md`

Multiple tasks? Read multiple files. The references are self-contained.

Success criteria: Only the task-relevant NestJS conventions are in play.

使用路由表选择参考文件。不要批量加载完整的参考树。

任务	需阅读的文件
NestJS版本、ORM、核心依赖、CLI、项目布局	`references/stack.md`
文件夹规范、模块组织、桶导出	`references/project-structure.md`
创建或编辑模块	`references/modules.md`
控制器、路由装饰器、请求生命周期	`references/controllers.md`
服务、提供者、依赖注入	`references/providers.md`
DTO、class-validator、ValidationPipe、转换	`references/validation.md`
TypeORM实体、仓库、迁移	`references/typeorm.md`
Prisma与NestJS的集成	`references/prisma.md`
守卫、认证、授权、JWT、Passport	`references/auth.md`
拦截器、日志、缓存、响应映射	`references/interceptors.md`
管道、自定义验证、参数转换	`references/pipes.md`
异常过滤器、自定义异常、错误响应	`references/error-handling.md`
BullMQ队列、处理器、流程	`references/queues.md`
WebSocket网关、事件、房间	`references/websockets.md`
微服务、传输方式、消息模式	`references/microservices.md`
OpenAPI/Swagger装饰器、 schema生成	`references/openapi.md`
单元测试、端到端测试、测试模块、模拟	`references/testing.md`
配置、ConfigModule、环境变量验证	`references/config.md`
中间件、生命周期钩子、关闭流程	`references/middleware.md`
使用pino或内置日志器记录日志	`references/logging.md`
健康检查、Terminus	`references/health.md`
CQRS、事件、sagas	`references/cqrs.md`
调度、定时任务、间隔任务	`references/scheduling.md`
Docker、部署、生产环境配置	`references/docker.md`

涉及多个任务？阅读多个文件。所有参考文件都是独立的。

成功标准：仅应用与任务相关的NestJS规范。

Step 2: Implement with the core NestJS guardrails

步骤2：遵循核心NestJS约束实现

Keep these rules active:

every module declares its controllers, providers, imports, and exports explicitly
controllers validate via DTOs +
```
ValidationPipe
```
, delegate to services, return typed responses
services contain business logic, injected via constructor — never instantiated with
```
new
```
entities/models are separate from DTOs — never return a raw entity from a controller
guards handle auth/authz, interceptors handle cross-cutting concerns, pipes handle transformation
all external input has a DTO with class-validator decorators
database mutations wrapped in transactions where atomicity matters
use
```
@nestjs/config
```
with Zod or Joi validation for env vars

Success criteria: The change fits the project's NestJS module architecture instead of bypassing the framework.

始终遵守以下规则：

每个模块都显式声明其控制器、提供者、导入项和导出项
控制器通过DTO +
```
ValidationPipe
```
进行验证，委托给服务，返回类型化响应
服务包含业务逻辑，通过构造函数注入——绝对不要用
```
new
```
实例化
实体/模型与DTO分离——绝对不要从控制器返回原始实体
守卫处理认证/授权，拦截器处理横切关注点，管道处理转换
所有外部输入都要有带class-validator装饰器的DTO
数据库变更在需要原子性的情况下要包裹在事务中
使用
```
@nestjs/config
```
搭配Zod或Joi验证环境变量

成功标准：代码变更符合项目的NestJS模块架构，而非绕过框架。

Step 3: Verify the affected surface

步骤3：验证受影响的代码范围

Use the narrowest relevant verification:

unit tests (
```
jest --testPathPattern=<module>
```
)
e2e tests (
```
jest --config test/jest-e2e.json
```
)
type checking (
```
tsc --noEmit
```
)
linting (
```
eslint .
```
)
OpenAPI spec regeneration if decorators changed

Success criteria: The changed NestJS surface still builds, type-checks, and passes tests.

使用最精准的相关验证方式：

单元测试（
```
jest --testPathPattern=<module>
```
）
端到端测试（
```
jest --config test/jest-e2e.json
```
）
类型检查（
```
tsc --noEmit
```
）
代码检查（
```
eslint .
```
）
如果装饰器有变更，重新生成OpenAPI规范

成功标准：受影响的NestJS代码仍可构建、通过类型检查并通过测试。

Guardrails

约束规则

Do not inline the whole NestJS handbook in
```
SKILL.md
```
.
Do not skip
```
references/stack.md
```
.
Do not put business logic in controllers — delegate to services.
Do not return raw entities — use DTOs or serialization interceptors.
Do not bypass dependency injection — never
```
new Service()
```
.
Do not create circular module dependencies without exhausting alternatives first.
Do not use
```
@nestjs/common
```
barrel imports for types — import from specific subpaths when possible.
Do not add
```
disable-model-invocation
```
; this is a normal domain skill.

不要在
```
SKILL.md
```
中内联完整的NestJS手册内容。
不要跳过
```
references/stack.md
```
。
不要在控制器中放置业务逻辑——委托给服务。
不要返回原始实体——使用DTO或序列化拦截器。
不要绕过依赖注入——绝对不要使用
```
new Service()
```
。
在未穷尽所有替代方案前，不要创建循环模块依赖。
不要使用
```
@nestjs/common
```
的桶导入类型——尽可能从特定子路径导入。
不要添加
```
disable-model-invocation
```
；这是一个常规领域技能。

When To Load References

何时加载参考内容

```
references/stack.md
```
Always.
then only the task-relevant files under
```
references/
```

```
references/stack.md
```
始终需要加载。
然后仅加载
```
references/
```
目录下与任务相关的文件

Output Contract

输出约定

Report:

which NestJS references were loaded
the module and architecture pattern chosen
the change made
the verification run

需报告：

加载了哪些NestJS参考内容
选择的模块和架构模式
做出的变更
执行的验证操作