nest架构

Nest.js 标准架构是4 层核心分层 + 2 层扩展层 ，遵循模块化、依赖注入、SOLID 原则，从请求入口到数据库 / 外部服务，层层解耦、职责单一。下面用表格 + 架构图 + 代码示例 + 边界说明讲清楚，一眼看懂层级关系与调用链路。

一、核心 4 层（必掌握，标准请求流）

1. 核心分层总表（从上到下：请求→响应）

层级	英文名称	核心职责	核心注解 / 类	调用顺序	边界（只做什么、不做什么）
控制器层	Controller	接收 HTTP 请求、路由分发、参数校验、返回响应	@Controller(), @Get(), @Post(), @Body(), @Param()	第 1 层（入口）	只处理 HTTP 相关：路由、请求 / 响应格式、状态码；不写业务逻辑、不操作数据库
服务层	Service	核心业务逻辑、数据处理、事务、业务规则	@Injectable(), @Service()	第 2 层（被 Controller 注入调用）	封装所有业务规则；不处理 HTTP、不直接写 SQL，只调用 Repository/DAO
数据访问层	Repository/DAO	数据库 CRUD、ORM 操作、原生 SQL、事务管理	TypeORM @Entity(), Repository, @InjectRepository()	第 3 层（被 Service 注入调用）	只做数据持久化：表映射、查询、写入；不写业务逻辑、不感知 HTTP
实体层	Entity/Model	数据库表结构映射、字段定义、关系、校验	TypeORM @Entity(), @Column(), @PrimaryGeneratedColumn()	第 4 层（数据载体，被 Repository/Service 使用）	纯数据结构、无业务逻辑、无数据库操作

2. 标准请求调用链路（HTTP → 数据库）

plaintext

客户端请求 → 中间件/守卫/拦截器 → Controller（路由匹配、参数提取） → Service（执行业务） → Repository（操作DB） → Entity（数据结构） → 数据库
响应原路返回 ← Controller封装响应 ← Service返回结果 ← Repository返回数据 ← Entity映射结果 ← 数据库

二、扩展 2 层（增强架构，非必须但常用）

扩展分层表

层级	英文名称	核心职责	核心注解	位置
中间件层	Middleware	请求预处理：日志、跨域、请求头处理、鉴权前置	@Middleware(), NestMiddleware	Controller 之前，全局 / 路由级
通用增强层	Guard/Interceptor/Pipe/Filter	守卫（权限）、拦截器（响应格式化 / 日志）、管道（参数转换 / 校验）、过滤器（异常处理）	@Guard(), @UseInterceptors(), @Pipe(), @Filter()	Controller 前后，切面式增强

三、完整架构分层图（文字版）

┌─────────────────────────────────────────────────────────────┐
│  外部层：客户端(HTTP/REST)、WebSocket、微服务、定时任务      │
└───────────────────────┬─────────────────────────────────────┘
                         │
┌───────────────────────▼─────────────────────────────────────┐
│  增强层：Middleware(中间件) → Guard(守卫) → Pipe(管道)        │
│          Interceptor(拦截器) → ExceptionFilter(异常过滤器)    │
└───────────────────────┬─────────────────────────────────────┘
                         │
┌───────────────────────▼─────────────────────────────────────┐
│  控制器层(Controller)：@Controller() → 路由、参数、响应       │
└───────────────────────┬─────────────────────────────────────┘
                         │ (依赖注入)
┌───────────────────────▼─────────────────────────────────────┐
│  服务层(Service)：@Injectable() → 业务逻辑、事务、规则        │
└───────────────────────┬─────────────────────────────────────┘
                         │ (依赖注入)
┌───────────────────────▼─────────────────────────────────────┐
│  数据访问层(Repository)：TypeORM Repository → CRUD、SQL       │
└───────────────────────┬─────────────────────────────────────┘
                         │
┌───────────────────────▼─────────────────────────────────────┐
│  实体层(Entity)：@Entity() → 表结构、字段、关系映射           │
└───────────────────────┬─────────────────────────────────────┘
                         │
┌───────────────────────▼─────────────────────────────────────┐
│  数据层：MySQL/PostgreSQL/MongoDB、Redis、外部API、文件       │
└─────────────────────────────────────────────────────────────┘

四、代码示例（对应 4 层，直观验证）

1. 实体层（Entity）：user.entity.ts

import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';

@Entity('user') // 映射数据库user表
export class UserEntity {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ length: 50 })
  username: string;

  @Column()
  password: string;
}

2. 数据访问层（Repository）：user.repository.ts（TypeORM 自动生成，无需手动写）

// TypeORM自动注入，直接使用Repository<UserEntity>
import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { UserEntity } from './user.entity';

@Injectable()
export class UserRepository {
  constructor(
    @InjectRepository(UserEntity)
    private readonly repository: Repository<UserEntity>,
  ) {}

  // 数据库查询
  async findById(id: number): Promise<UserEntity | null> {
    return this.repository.findOneBy({ id });
  }
}

3. 服务层（Service）：user.service.ts

import { Injectable } from '@nestjs/common';
import { UserRepository } from './user.repository';
import { UserEntity } from './user.entity';

@Injectable()
export class UserService {
  constructor(private readonly userRepository: UserRepository) {}

  // 业务逻辑：查询用户+业务校验
  async getUserById(id: number): Promise<UserEntity> {
    const user = await this.userRepository.findById(id);
    if (!user) throw new Error('用户不存在');
    return user;
  }
}

4. 控制器层（Controller）：user.controller.ts

import { Controller, Get, Param } from '@nestjs/common';
import { UserService } from './user.service';
import { UserEntity } from './user.entity';

@Controller('users') // 路由前缀 /users
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Get(':id') // 路由 GET /users/1
  async getUser(@Param('id') id: string): Promise<UserEntity> {
    // 只处理HTTP参数，调用Service，返回响应
    return this.userService.getUserById(+id);
  }
}

五、关键架构原则 & 边界（避坑）

1. 单向依赖，禁止跨层调用 ：Controller → Service → Repository → Entity，禁止 Service 直接调用 Controller、Repository 调用 Service
2. 依赖注入（DI）贯穿全层：所有层通过构造器注入，解耦、易测试
3. 单一职责：每层只做一件事，Controller 不写业务、Service 不写 SQL、Entity 无逻辑
4. 模块化组织：按功能模块（如 user、order）封装 4 层，而非按层拆分所有代码

六、补充：进阶扩展层（可选）

• DTO 层：Data Transfer Object，参数校验、请求 / 响应格式定义（配合 Pipe）
• DAO 层：复杂多表查询、原生 SQL 封装（替代 Repository）
• 微服务层：跨服务调用（ClientProxy、MessagePattern）

贴合「控制器 / 服务 / 仓储 / 实体 / DTO / 中间件 / 过滤器」全分层，直接落地开发，适配 TypeORM + JWT + 全局拦截校验。

一、根目录总览

src/
├── main.ts                # 项目入口、启动服务、全局配置
├── app.module.ts          # 根模块
├── common/                # 全局通用层（核心公共能力）
├── config/                # 配置文件（环境变量、数据库、JWT）
├── modules/               # 业务模块（按功能拆分，核心业务）
└── utils/                 # 工具函数、通用方法

---

二、分层详细目录（带注解）

1. 全局通用层 src/common/（所有模块共用）

common/
├── decorators/        # 自定义装饰器（获取当前用户、角色校验）
│   └── current-user.decorator.ts
├── filters/           # 全局异常过滤器（统一报错格式）
│   └── http-exception.filter.ts
├── guards/            # 守卫（JWT鉴权、角色权限）
│   ├── jwt-auth.guard.ts
│   └── role.guard.ts
├── interceptors/      # 全局拦截器（统一响应格式化、日志、超时）
│   └── transform.interceptor.ts
├── middlewares/       # 自定义中间件（请求日志、Header处理）
│   └── logger.middleware.ts
├── pipes/             # 全局管道（参数校验、类型转换）
│   └── validation.pipe.ts
└── constants/         # 全局常量（状态码、提示语）
    └── error-code.constant.ts

2. 配置层 src/config/

config/
├── database.config.ts  # TypeORM 数据库配置
├── jwt.config.ts       # JWT 密钥、过期时间
└── env.config.ts       # 环境变量读取（dev/prod）

3. 工具层 src/utils/

utils/
├── crypto.util.ts      # 加密工具（密码加盐hash、MD5）
├── date.util.ts        # 时间格式化
└── validate.util.ts    # 通用正则校验

4. 核心业务模块 src/modules/（标准单模块结构，多模块复制即可）

遵循：一个业务一个文件夹，内部完整分层

modules/
├── user/                   # 用户模块
│   ├── dto/                # DTO层：请求/响应参数校验
│   │   ├── create-user.dto.ts
│   │   └── login-user.dto.ts
│   ├── entities/           # 实体层：数据库表映射
│   │   └── user.entity.ts
│   ├── repositories/       # 仓储层：纯数据库CRUD
│   │   └── user.repository.ts
│   ├── user.controller.ts  # 控制器层：路由+接收请求
│   ├── user.service.ts     # 服务层：核心业务逻辑
│   └── user.module.ts     # 模块入口：依赖注入整合
│
└── order/                  # 订单模块（同结构复制）
    ├── dto/
    ├── entities/
    ├── repositories/
    ├── order.controller.ts
    ├── order.service.ts
    └── order.module.ts

---

三、关键核心文件极简说明

1. main.ts全局挂载：拦截器、过滤器、校验管道、跨域、静态资源
2. app.module.ts导入所有业务模块、数据库模块、配置模块
3. DTO 作用 配合 class-validator 做入参校验，禁止 Controller 裸拿参数
4. Repository 作用抽离所有 SQL/ORM 操作，Service 只写业务，完全解耦

---

四、最简调用链路（对应目录）

客户端请求
→ common/守卫/中间件/管道
→ modules/xxx/xxx.controller.ts（路由）
→ modules/xxx/xxx.service.ts（业务）
→ modules/xxx/repositories/xxx.repository.ts（操作数据库）
→ modules/xxx/entities/xxx.entity.ts（表结构）
→ 数据库

---

五、附加：配套依赖（新建项目直接装）

# ORM+校验+JWT
npm install @nestjs/typeorm typeorm mysql2 class-validator class-transformer @nestjs/jwt bcryptjs