1 / 4概念
Identity: Backend Frameworks
NestJS 把 Node 服务拆成模块、控制器和提供者,用依赖注入和装饰器把鉴权、校验、日志等横切关注点集中到请求生命周期里。判断标准不是“像不像 Spring”,而是边界是否清楚、依赖图是否可测、请求生命周期是否可预测。
1 概念
1.1 一句话定义
NestJS 是一个带约定结构的 Node.js 服务端框架:模块(module)组织边界,控制器(controller)接 HTTP,提供者(provider)承载业务与基础设施,依赖注入(DI)装配对象,守卫/拦截器/管道/过滤器处理横切逻辑。
1.2 它解决什么问题
- 结构统一:模块、控制器、服务分层,团队不必为每个接口重新发明目录结构。
- 依赖可测:构造函数注入让替换数据库、时钟、外部客户端变得简单。
- 横切集中:鉴权、校验、日志、超时、异常映射各有一个明确位置。
- 生命周期可预测:中间件 → 守卫 → 拦截器 → 管道 → 处理器 → 过滤器,顺序固定。
没有这些约定,Express 也能写服务;但接口一多,鉴权和校验会散落在每个 handler 里,测试和排错成本快速上升。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| JS/TS 类型、装饰器、模块语义 | JavaScript / TypeScript Language Basics |
| Node 事件循环、线程池、内存 | Runtime Environment |
| HTTP 协议、TLS、负载均衡 | Application Protocols |
| 数据库事务、索引与执行计划 | Relational Databases |
| 微服务拆分与事件驱动 | Microservices / Event-Driven Architecture |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| Module | 一组控制器/提供者的边界 | 不是 npm 包 |
| Controller | 声明路由并处理 HTTP 请求 | 不该放业务逻辑 |
| Provider | 可被注入的类/值/工厂 | 不等于 service |
| DI 容器 | 按 token 解析依赖图 | 不是全局单例 |
| Guard | 在 handler 前决定是否放行 | 不是中间件 |
| Interceptor | 包裹 handler,前后加工 | 不是 middleware |
| Pipe | 转换/校验参数 | 不负责鉴权 |
| Exception Filter | 捕获异常并映射响应 | 不负责业务回滚 |
| DTO | 数据传输对象,定义入参/出参形状 | 不是数据库实体 |
| Scope | 提供者生命周期:singleton/request/transient | 不是 HTTP scope |
2 机制
2.1 心智模型
把 Nest 应用想成一张依赖图:启动时扫描模块,按 token 装配 provider,再把控制器方法绑定到路由。请求进来后沿固定管线穿过中间件、守卫、拦截器、管道,进入 handler,再沿拦截器和异常过滤器返回。业务逻辑在 provider,控制器只做协议适配。
2.2 机制拆解
- 启动:
NestFactory.create(AppModule)扫描模块元数据,构建 DI 图,实例化 provider,绑定路由;循环依赖会在启动时报错。 - 请求管线:中间件(全局/模块)→ 守卫(全局/控制器/方法)→ 拦截器前置 → 管道(参数校验/转换)→ handler → 拦截器后置 → 异常过滤器。
- 模块边界:
imports引入其他模块导出的 provider;providers在本模块内可注入;exports决定对外可见性。 - 作用域:默认 singleton;
Scope.REQUEST每个请求新建;Scope.TRANSIENT每个注入点新建。请求作用域会向上传播,成本高。 - 校验:
ValidationPipe配合 class-validator/class-transformer;whitelist删除未声明字段,forbidNonWhitelisted直接拒绝。 - 异常:
HttpException子类映射状态码;全局过滤器统一错误结构,不要把内部堆栈返回给客户端。
2.3 完整枚举
Nest 的构建块:
| 构建块 | 声明方式 | 职责 | 不该做什么 |
|---|---|---|---|
| Module | @Module() | 组织边界、导入导出 | 不写业务逻辑 |
| Controller | @Controller() | 路由、参数、响应 | 不直接访问数据库 |
| Provider | @Injectable() | 业务/基础设施 | 不读 HTTP 上下文 |
| Guard | @UseGuards() | 鉴权、放行 | 不做参数校验 |
| Interceptor | @UseInterceptors() | 日志、超时、响应映射 | 不吞异常 |
| Pipe | @UsePipes() | 转换、校验 | 不做权限判断 |
| Filter | @Catch() | 异常映射 | 不掩盖未知错误 |
| Middleware | configure() | 原始请求预处理 | 不依赖 DI 的请求作用域 |
请求生命周期顺序(完整集合):
| 顺序 | 阶段 | 典型用途 |
|---|---|---|
| 1 | 中间件 | 请求 ID、原始日志、CORS |
| 2 | 守卫 | 认证、角色/权限 |
| 3 | 拦截器(前) | 计时、缓存读、上下文 |
| 4 | 管道 | DTO 校验、类型转换 |
| 5 | 控制器/提供者 | 业务用例 |
| 6 | 拦截器(后) | 响应包装、缓存写 |
| 7 | 异常过滤器 | 错误结构、状态码 |
Provider 作用域:
| 作用域 | 实例数 | 成本 | 适用 |
|---|---|---|---|
DEFAULT(singleton) | 每应用一个 | 最低 | 无请求状态的服务 |
REQUEST | 每请求一个 | 高,向上传播 | 需要请求上下文 |
TRANSIENT | 每注入点一个 | 中 | 有状态的工具/策略 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 启动时间 | 数百 ms 到数秒 | 模块与 provider 越多越慢 |
| 请求作用域成本 | 每请求新建对象 | 高 QPS 下明显 |
| 默认请求体上限 | 约 100 KB | 由 body parser 配置 |
| 校验开销 | 微秒到毫秒 | 取决于 DTO 复杂度 |
| 默认超时 | 无 | 必须显式设置 |
3 实践
3.1 最小示例
// users.module.ts:模块把控制器与提供者收在一起。
@Module({controllers: [UsersController], providers: [UsersService], exports: [UsersService]})
export class UsersModule {}
// users.controller.ts:只做协议适配,业务在 UsersService。
@Controller('users')
export class UsersController {
constructor(private readonly users: UsersService) {}
@Get(':id')
findOne(@Param('id', ParseUUIDPipe) id: string) {
return this.users.findOne(id);
}
@Post()
create(@Body() input: CreateUserDto) {
return this.users.create(input);
}
}
// create-user.dto.ts:运行时校验,类型本身不校验请求体。
export class CreateUserDto {
@IsString()
@MaxLength(80)
name!: string;
@IsEmail()
email!: string;
}
3.2 常用操作与参数
| 操作 | 命令 / API | 说明 |
|---|---|---|
| 全局校验 | app.useGlobalPipes(new ValidationPipe({whitelist: true, forbidNonWhitelisted: true})) | 边界统一 |
| 异常映射 | @Catch(HttpException) | 统一错误结构 |
| 测试 | Test.createTestingModule() | 替换 provider |
3.3 标准流程
- 先划模块边界:一个业务能力一个模块,模块之间通过导出的 provider 通信。
- 写 DTO,打开全局校验;入参在边界被拒绝,不进入业务层。
- 控制器只做协议适配,业务用例放进 service。
- 鉴权放 guard,日志/超时/响应包装放 interceptor,异常映射放 filter。
- 数据库访问通过 repository/port 注入;单元测试用
Test.createTestingModule(),e2e 走真实 HTTP。
3.4 与相邻技术的组合
- Node 运行时:请求处理跑在事件循环上;同步阻塞会拖慢所有请求。
- 关系型数据库:service 管用例,repository 管持久化与事务边界。
- 微服务:模块边界是拆分前提;跨模块调用先走进程内接口,再评估消息。
- OpenAPI/前端:DTO 与装饰器生成契约,但运行时仍要校验。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 团队规模 | 小 / 大 | 约定越强,协作成本越低 |
| 结构需求 | 简单 API / 多模块服务 | Nest 的模块与 DI 是否值得 |
| 校验策略 | DTO 类 / schema | class-validator 或 zod |
| 作用域 | singleton / request | 性能与上下文传递 |
| 部署形态 | 长驻 / Serverless | 启动时间与冷启动 |
3.6 决策规则
- 多模块、需要统一鉴权/校验/文档:Nest;单端点小服务:Express/Fastify 更轻。
- 入参校验用 DTO + 全局
ValidationPipe,不要在每个 handler 手写。 - 鉴权放 guard,不要放 interceptor;拦截器不应决定“能不能进”。
- 默认 singleton;只有确实需要请求上下文时才用
Scope.REQUEST。 - 错误结构由全局 filter 统一,业务层只抛领域异常。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| NestJS | 结构强、DI、生态完整 | 概念多、启动较重 | 中大型服务 |
| Express | 轻、自由、生态老 | 约定靠团队 | 小服务、边缘函数 |
| Fastify | 快、schema 友好 | 生态较 Express 小 | 高吞吐 API |
| class-validator | 与 Nest 集成好 | 装饰器 + 反射 | DTO 类 |
| zod | 类型推导强、无反射 | 需适配管道 | 函数式/schema 优先 |
3.8 何时不该用
- 单个无状态端点:不要引入完整 Nest 结构,Express/Fastify 足够。
- Serverless 冷启动敏感:评估 DI 扫描与启动成本。
- 团队不熟装饰器/DI:先用显式函数组合,避免“魔法”失控。
- 高 QPS 热路径:避免请求作用域 provider 和重量级拦截器。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 启动时报依赖解析失败 | provider 未注册或未导出 | 检查 providers/exports/imports |
| 路由 404 | 控制器前缀或全局前缀不匹配 | 检查 @Controller 与 setGlobalPrefix |
| 校验没生效 | 管道未全局注册或 transform 关闭 | 注册 ValidationPipe 并开 transform |
| 守卫顺序不符预期 | 全局/控制器/方法级守卫叠加 | 明确执行顺序,避免重复鉴权 |
| 请求数据串了 | singleton 持有请求状态 | 改请求作用域或 AsyncLocalStorage |
| 异常被吞成 200 | interceptor 未重新抛出 | 用 catchError 转发 |
| 循环依赖启动失败 | 模块互相 import | 拆模块或用 forwardRef |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
| 控制器里写业务和 SQL | 难测、难复用 | service + repository |
把 REQUEST 注入 singleton | 请求间数据污染 | 请求作用域/上下文服务 |
DTO 用 any | 校验与文档失效 | 明确字段与装饰器 |
| 全局守卫做副作用 | 难追踪、重复执行 | 纯鉴权,副作用放拦截器 |
| 捕获所有异常返回 200 | 客户端无法重试/告警 | 映射正确状态码 |
4.3 可观测信号
Nest Logger、请求 ID、DI 启动错误、校验错误率、拦截器耗时、OpenAPI diff、事件循环延迟、P99 延迟。
4.4 安全 / 性能 / 一致性边界
- 鉴权边界:guard 决定能否进入;不要在 handler 里“顺便”检查权限。
- 校验边界:管道只校验形状,业务规则仍在 service;不要用类型断言替代校验。
- 事务边界:事务应包住一个用例,不要跨控制器/拦截器。
- 性能边界:请求作用域和同步阻塞会放大延迟;热路径保持 singleton。