NestJS：企业级 Node.js Web 后端框架-马育民老师

# 介绍

NestJS（简称 Nest）是一套**基于 Node.js 的企业级后端开发框架**，2017 年由 Kamil Myśliwiec 开源，核心基于 TypeScript 构建，同时兼容纯 JavaScript。
底层封装两大主流 Node HTTP 库：**Express（默认）**、Fastify（高性能替代）。

### 定位
解决原生 Express/Koa 无规范、代码混乱、难以大型团队协作的痛点；借鉴 Java Spring、Angular 的分层架构思想，提供标准化、模块化、可测试的后端开发体系，适合中大型服务、微服务、API 网关。

### 特点

1. **强 TypeScript 原生支持**：装饰器、依赖注入、类型校验、接口、泛型深度融合；
2. **模块化分层架构**：Module / Controller / Service 三层标准结构；
3. **完整依赖注入（DI）**：解耦业务，单元测试零成本；
4. **开箱即用中间件体系**：拦截器、管道、过滤器、守卫；
5. **多协议支持**：HTTP API、WebSocket、GRPC、MQTT；
6. **微服务原生内置**：TCP、Redis、RabbitMQ、Kafka 多通信方案；
7. **丰富生态**：ORM（TypeORM/Prisma）、Swagger 文档、缓存、日志、定时任务；
8. **跨平台**：可打包为单文件、部署容器、Serverless。

# 架构分层
### 1. Module 模块（模块容器）
**最小组织单元**，类似 Spring 的 `@Configuration`，用来封装一组相关业务控制器、服务、依赖。
装饰器：`@Module()`
模块组成：
- `controllers`：当前模块控制器
- `providers`：服务、工具类、依赖注入对象
- `imports`：导入其他模块（共享服务）
- `exports`：导出当前模块提供者，供外部模块使用

示例基础模块：
```typescript
@Module({
  controllers: [UserController],
  providers: [UserService],
  exports: [UserService] // 导出后其他模块可注入 UserService
})
export class UserModule {}
```

#### 模块分类
1. **根模块（AppModule）**：程序入口，唯一根模块；
2. **功能模块**：UserModule、OrderModule 业务模块；
3. **共享模块（SharedModule）**：全局通用工具、过滤器、管道；
4. **全局模块**：`@Global()` 修饰，无需手动 import 全项目可用。

### 2. Controller 控制器（请求入口）
负责**接收 HTTP 请求、路由分发、参数接收、返回响应**，只做请求转发，不写业务逻辑。
装饰器：`@Controller()`、`@Get()`/`@Post()`/`@Put()`/`@Delete()`

职责边界：
- 获取请求参数（路径参数、query、body、header）
- 调用 Service 执行业务
- 统一返回结果

示例：
```typescript
@Controller('user') // 路由前缀 /user
export class UserController {
  constructor(private userService: UserService) {} // 注入服务

@Get(':id')
  findOne(@Param('id') id: string) {
    return this.userService.getById(+id);
  }
}
```

### 3. Provider 提供者（业务逻辑层，核心是 Service）
所有可被 DI 注入的类都叫 Provider，最常用为 Service。
装饰器：`@Injectable()`
**职责：纯业务逻辑、数据库操作、计算、第三方调用**，控制器只调用服务，实现分层解耦。

```typescript
@Injectable()
export class UserService {
  getById(id: number) {
    return { id, name: 'test' };
  }
}
```

# 八大核心内置能力
### 1. 依赖注入 DI（框架灵魂）
#### 作用
自动管理类实例生命周期，无需手动 new，实现低耦合、易单测。
#### 注入规则
1. `@Injectable()` 标记可注入类；
2. 构造函数声明依赖，框架自动实例化传入；
3. 支持单例（默认全局单例）、请求级实例；
4. 自定义注入 Token，可注入常量、工厂函数。

### 2. 中间件 Middleware
和 Express 中间件一致，在路由匹配**前**执行：日志、跨域、请求改写、token 初步校验。
两种写法：函数中间件 / Nest 类中间件（`@Injectable()` + `implements NestMiddleware`）
注册位置：`AppModule` 的 `configure()`。

### 3. 守卫 Guard（鉴权/权限控制）
在路由执行前拦截，**判断是否允许访问接口**，返回 true/false。
常用场景：登录校验、角色权限（admin/user）。
装饰器：`@UseGuards()`
内置：`AuthGuard`，配合 JWT 实现登录鉴权。

### 4. 管道 Pipe（参数校验 & 转换）
接收请求参数后、进入控制器前执行：
- 类型转换（string 转 number）
- 参数校验（必填、长度、正则）
主流配套：`class-validator` + `class-transformer`，全局统一校验 DTO。

### 5. 拦截器 Interceptor
请求前后双拦截：
1. 请求前：修改入参、日志计时；
2. 响应后：统一封装返回格式、异常捕获、缓存；
统一返回示例：`{ code:200, data:xxx, msg:"success" }`

### 6. 异常过滤器 ExceptionFilter
统一捕获全局/控制器/接口异常，格式化错误返回，避免原生 Express 杂乱报错。
内置 `HttpException`，可自定义业务异常（400、401、403、500）。

### 7. 装饰器 Decorator（元数据标记）
分为两类：
1. **类装饰器**：`@Module`、`@Controller`、`@Injectable`；
2. **方法/参数装饰器**：`@Get`、`@Param`、`@Body`、`@Query`、`@Roles`（自定义权限）；
支持自定义装饰器扩展业务标记。

### 8. DTO 数据传输对象
配合管道做请求体强类型校验，区分入参结构，避免 any 类型：
```typescript
export class CreateUserDto {
  @IsString()
  @Length(2,10)
  name: string;

@IsEmail()
  email: string;
}
```

# 生命周期

请求完整执行流程

1. 请求到达 → 全局中间件
2. 路由中间件
3. 守卫 Guard
4. 拦截器（前置）
5. 管道 Pipe 参数校验转换
6. Controller 方法执行 → 调用 Service
7. 拦截器（后置，封装返回）
8. 异常过滤器（发生错误时触发）

# 微服务能力（Nest 一大优势）

Nest 原生支持微服务架构，一套代码切换多种传输协议：

1. **TCP（默认）**
2. Redis 发布订阅
3. RabbitMQ / Kafka 消息队列
4. GRPC 高性能二进制协议
5. MQTT 物联网

### 微服务架构模式

- 单体拆分多微服务；
- API Gateway（Nest 网关）统一接收前端 HTTP，转发内部微服务；
- 服务间解耦通信，支持事件驱动。

# 常用配套生态
### 1. 数据库
- TypeORM：SQL 数据库（MySQL/PostgreSQL/SQLite）ORM
- Prisma：现代化类型安全 ORM（当下主流）
- Mongoose：MongoDB ODM

### 2. 文档
`@nestjs/swagger`：自动生成 OpenAPI / Swagger 接口文档，DTO、路由自动解析。

### 3. 安全
- JWT 登录鉴权：`@nestjs/jwt` + passport
- Passport：多登录策略（账号密码、OAuth、Github）
- CORS、CSRF、请求限流

### 4. 工具
- `@nestjs/config`：环境变量管理（.env 多环境区分 dev/prod）
- `@nestjs/cache-manager`：Redis 缓存
- `@nestjs/schedule`：定时任务 Cron
- Winston / Pino：日志框架
- Fastify：替换 Express，性能提升 2~5 倍

# 项目标准目录结构
```
src/
├── main.ts                # 程序入口，创建 Nest 应用
├── app.module.ts          # 根模块
├── common/                 # 公共通用层
│   ├── filters/           # 全局异常过滤器
│   ├── guards/            # 权限守卫
│   ├── interceptors/      # 统一响应拦截器
│   ├── pipes/             # 参数校验管道
│   └── decorators/        # 自定义装饰器
├── config/                # 配置文件、环境变量
├── modules/               # 业务模块（按业务拆分）
│   ├── user/
│   │   ├── dto/           # 请求DTO
│   │   ├── user.controller.ts
│   │   ├── user.service.ts
│   │   └── user.module.ts
│   └── order/
├── database/              # 数据库连接、实体、迁移
└── utils/                 # 工具函数
```

# 优缺点
### 优点
1. 强 TS 类型约束，大型项目可维护性极高；
2. 架构规范统一，团队协作无代码风格混乱；
3. 内置全套企业级能力，不用自己封装校验、鉴权、统一返回；
4. 微服务、网关、RPC 原生支持，适合分布式系统；
5. 装饰器语法清晰，学习过 Spring/Angular 上手极快；
6. 丰富官方插件，生态成熟。

### 缺点
1. 学习曲线高于 Express/Koa，新手需要理解 DI、装饰器、分层；
2. 小型简单接口项目略显笨重；
3. 编译阶段依赖 TS，开发启动速度略慢于原生 JS 框架；
4. 相比 Go/SpringBoot，Node 底层并发性能上限更低。

# 适用场景

### ✅ 推荐使用：

- 中大型企业后台 API、管理系统；
- 微服务、分布式后端；
- 需要严格接口规范、自动文档、权限控制；
- 团队多人协作长期维护项目；
- 同时需要 HTTP + 消息队列 + GRPC 混合服务。

### ❌ 不推荐：

- 超简单轻量脚本、临时小接口；
- 极致追求极简、零依赖小型工具服务。

# 快速最小示例演示

### 1. 安装脚手架
```bash
npm i -g @nestjs/cli
nest new nest-demo
cd nest-demo
```

### 2. 生成 User 模块
```bash
nest g module user
nest g controller user
nest g service user
```

### 3. main.ts 入口
```typescript
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
  console.log('服务启动：http://localhost:3000');
}
bootstrap();
```

### 4. 完整请求链路
1. AppModule 导入 UserModule；
2. UserController 接收 `/user` 请求；
3. 构造函数注入 UserService；
4. Controller 调用 Service 获取数据返回；
5. 全局拦截器统一包装返回格式。

# 和 Express / Koa / SpringBoot 对比

1. **vs Express/Koa**
   Express 是基础 http 库，无架构规范；Nest 基于 Express 封装完整分层、DI、微服务体系，开箱即用企业能力。
2. **vs SpringBoot**
   设计思想高度相似（DI、分层、注解）；Spring 基于 Java，Nest 基于 Node+TS，前端开发者无缝衔接，前后端语言统一。

原文出处：http://www.malaoshi.top/show_1GW3fpjTCZmV.html