pnpm dlx @nestjs/cli new my-app      # 或 npx nest new my-app
cd my-app
pnpm start:dev                        # http://localhost:3000

my-app/
├── src/
│   ├── main.ts                   # 入口：创建 app、挂全局件、listen(3000)
│   ├── app.module.ts             # 根模块：装配所有子模块的入口
│   ├── app.controller.ts         # 示例控制器（GET /）
│   ├── app.controller.spec.ts    # 上面控制器的单元测试
│   └── app.service.ts            # 示例 provider（被 controller 注入）
├── test/
│   ├── app.e2e-spec.ts           # e2e 测试示例（supertest 打真实接口）
│   └── jest-e2e.json             # e2e 的 jest 配置
├── ......
└── README.md

src/notes/
├── notes.module.ts          # 业务模块：登记下面的 controller / service
├── notes.controller.ts      # HTTP 层：路由 + 取参
├── notes.controller.spec.ts # controller 单元测试
├── notes.service.ts         # 业务逻辑层（provider）
├── notes.service.spec.ts    # service 单元测试
├── dto/
│   ├── create-note.dto.ts   # 创建请求体类型
│   └── update-note.dto.ts   # 更新请求体类型
└── entities/
    └── note.entity.ts       # 数据库表映射（ORM 实体）

NestFactory.create(AppModule)
  → 扫描器从根模块沿 imports 递归，收集所有 @Module
  → 读元数据建"模块图"
  → 容器按依赖链把所有 provider / controller 实例化、注入
  → 从 controller 的 @Get / @Post 生成路由表
  → app.listen()

请求 → Middleware → Guard → Interceptor(前) → Pipe → Controller 方法 → Interceptor(后) → 响应
       （任何一步抛异常 → Exception Filter）

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);   // 【装配】把 AppModule 交给容器，触发扫描 + 实例化
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { NotesModule } from './notes/notes.module';

@Module({
  imports: [NotesModule],          // 【装配】把 notes 业务模块挂进模块图
  controllers: [AppController],     // 示例控制器（Hello World，可删）
  providers: [AppService],          // 示例 provider（可删）
})
export class AppModule {}

import { Module } from '@nestjs/common';
import { NotesService } from './notes.service';
import { NotesController } from './notes.controller';

@Module({
  controllers: [NotesController],  // 【装配】要实例化的控制器
  providers: [NotesService],       // 【装配】要造、能注入的 provider
})
export class NotesModule {}

import { Controller, Get, Post, Body, Patch, Param, Delete } from '@nestjs/common';
import { NotesService } from './notes.service';
import { CreateNoteDto } from './dto/create-note.dto';
import { UpdateNoteDto } from './dto/update-note.dto';

@Controller('notes')                                    // 【贴标签】控制器，前缀 /notes
export class NotesController {
  constructor(private readonly notesService: NotesService) {}   // 【声明依赖】要 NotesService

  @Post()                           // 【贴标签】POST /notes
  create(@Body() createNoteDto: CreateNoteDto) { return this.notesService.create(createNoteDto); }

  @Get(':id')                       // 【贴标签】GET /notes/:id
  findOne(@Param('id') id: string) { return this.notesService.findOne(+id); }
  // 还有 findAll / update / remove，写法一样
}

import { Injectable } from '@nestjs/common';
import { CreateNoteDto } from './dto/create-note.dto';

@Injectable()                       // 【贴标签】可注入 provider
export class NotesService {
  create(createNoteDto: CreateNoteDto) { return 'This action adds a new note'; }   // 桩，先不接库
  findOne(id: number) { return `This action returns a #${id} note`; }
  // 还有 findAll / update / remove
}

应用对象
├── @Module()                    # 模块：声明一组 providers / controllers / imports / exports
├── @Controller()                # 控制器：聚合一组路由
└── @Injectable()                # provider 标记：可被 DI 容器管理的类

路由与参数
├── @Get @Post @Put @Patch @Delete   # 路由处理器
├── @Param @Query @Body            # 取路径参数 / 查询参数 / 请求体
├── @Headers @Ip @Session          # 取协议层信息
└── @Req @Res                      # 原始 Express / Fastify 对象

横切构件（按请求生命周期顺序）
├── Middleware                    # 中间件：最外层，能拿到
 Request/Response
├── Guard                         # 守卫：决定请求是否被允许进入
├── Interceptor                   # 拦截器：方法执行前后都能介入
├── Pipe                          # 管道：参数转换或校验
└── Exception Filter              # 异常过滤器：异常到响应的映射

异常与响应
├── HttpException 及其子类        # 内置异常：BadRequestException、NotFoundException 等
├── @Catch()                      # 自定义异常过滤器的作用范围
└── @Render()                     # 模板渲染（SSR 场景）

平台适配器(Express/Fastify) -> Nest app -> Module -> Controller -> Guard -> Interceptor -> Pipe -> Service

框架核心
├── @nestjs/common               # 装饰器、构件接口、工具
├── @nestjs/core                 # DI 容器、NestFactory、扫描器、实例加载器
└── @nestjs/platform-express     # 默认 HTTP 平台（基于 Express）
   └── express                   # 底层 Web 框架

元数据基础设施（DI 能工作的前提）
├── reflect-metadata             # 装饰器元数据的运行时存储
└── tsconfig: emitDecoratorMetadata + experimentalDecorators  # 编译期把类型信息写进元数据

配置层
└── @nestjs/config               # 读 .env / 环境变量，注入 ConfigService

数据校验层
├── class-validator              # 装饰器驱动的字段校验
├── class-transformer            # 普通对象 -> DTO 类实例
└── ValidationPipe               # Nest 自带管道，串起上面两个

数据库层
├── @nestjs/typeorm + typeorm    # TypeORM 集成（最主流）
├── @prisma/client / Prisma      # 或 Prisma
└── @nestjs/mongoose             # 或 Mongoose

认证授权层
├── @nestjs/jwt                  # JWT 签发与校验
├── @nestjs/passport + passport  # 护照策略集成（本地 / JWT / OAuth）
└── bcrypt / argon2              # 密码哈希

缓存与消息层
├── @nestjs/cache-manager        # 缓存抽象
├── @nestjs/bull / BullMQ        # 队列
└── @nestjs/microservices        # 微服务 / RPC（TCP、Redis、gRPC、Kafka）

运维与启动层
├── @nestjs/swagger              # 自动生成 OpenAPI 文档
├── @nestjs/cli                  # 脚手架与构建
└── pm2 / docker                 # 进程管理 / 容器化

my-app/                              # 工作区根（pnpm workspaces）
├── package.json                     # 声明 workspaces + 公共 dev 脚本
├── pnpm-workspace.yaml              # 列出 apps/* 和 packages/*
├── tsconfig.base.json               # 所有子包 extends 的基础 TS 配置
│
├── apps/
│   ├── api/                         # Nest 后端（内部就是上面的 src/ 结构）
│   │   ├── package.json             #   "@my/api"，依赖 @my/schemas
│   │   ├── tsconfig.json
│   │   └── src/ …                   #   main.ts / app.module.ts / modules/ …
│   └── web/                         # 前端（Vite / Next / React）
│       ├── package.json             #   "@my/web"，依赖 @my/schemas
│       └── src/ …
│
└── packages/
    └── schemas/                     # ★ 共享契约层（单一事实源）
        ├── package.json             #   "@my/schemas"
        ├── tsconfig.json
        └── src/
            ├── index.ts
            └── notes.schema.ts      #   Zod schema / class DTO，前后端都 import

浏览器 -> Express/Fastify -> Nest app(main.ts 装配出的)

pnpm start:dev      # = nest start --watch，开发热重启
node dist/main.js   # 生产环境直接跑编译产物

// src/main.ts
import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.setGlobalPrefix('api');                       // 所有路由加 /api 前缀
  app.useGlobalPipes(
    new ValidationPipe({ whitelist: true, transform: true }),
  );

  await app.listen(3000);
}
bootstrap();

// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { NotesModule } from './modules/notes/notes.module';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }), // 全局配置
    NotesModule,
  ],
})
export class AppModule {}

import { Body, Controller, Post } from '@nestjs/common';
import { NotesService } from './notes.service';

@Controller('notes')                 // 【贴标签】控制器，路由前缀 /notes
export class NotesController {
  constructor(private readonly notes: NotesService) {}   // 【声明依赖】要 NotesService

  @Post()                            // 【贴标签】POST /notes
  create(@Body() body: { title: string; content?: string }) {
    return this.notes.create(body);  // 交给 service，controller 不写业务
  }
}

import { Injectable } from '@nestjs/common';

@Injectable()                        // 【贴标签】可注入的 provider
export class NotesService {
  create(body: { title: string; content?: string }) {
    return { id: Date.now(), ...body };   // 暂不接库，直接造一条返回
  }
}

import { Module } from '@nestjs/common';
import { NotesController } from './notes.controller';
import { NotesService } from './notes.service';

@Module({
  controllers: [NotesController],    // 【装配】要实例化的控制器
  providers: [NotesService],         // 【装配】能造、能注入的 provider
})
export class NotesModule {}

// src/app.module.ts
import { Module } from '@nestjs/common';
import { NotesModule } from './modules/notes/notes.module';

@Module({ imports: [NotesModule] })
export class AppModule {}

pnpm start:dev

curl -X POST http://localhost:3000/notes \
  -H "Content-Type: application/json" \
  -d '{"title":"hello","content":"第一条"}'
# => {"id":1747...,"title":"hello","content":"第一条"}

// @Controller('notes') 本质是：一个接收前缀、返回“类装饰器”的函数
export const Controller = (prefix = '') =>
  (target) => {
    Reflect.defineMetadata('nest:controller', true, target);   // 标记“这是控制器”
    Reflect.defineMetadata('nest:path', prefix, target);       // 记下前缀 /notes
  };
// @Controller('notes') 执行时，只是在 NotesController 类上贴了两个键值对——不改类的行为，只是登记。

// @Post() 同理，只是标签贴在方法上（方法装饰器签名：target, key, descriptor）
export const Post = (path = '') =>
  (target, key, descriptor) => {
    Reflect.defineMetadata('nest:method', 'POST', target, key);
    Reflect.defineMetadata('nest:path', path, target, key);
  };

// src/modules/notes/notes.controller.ts
import { Body, Controller, Get, Param, Post, Query } from '@nestjs/common';
import { NotesService } from './notes.service';
import { CreateNoteDto } from './dto/create-note.dto';

@Controller('notes')
export class NotesController {
  // 构造函数注入：service 由 DI 容器提供
  constructor(private readonly notesService: NotesService) {}

  @Post()
  create(@Body() dto: CreateNoteDto) {
    return this.notesService.create(dto);
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.notesService.findOne(id);
  }
}

@Get()
findAll(@Query('skip') skip?: number, @Query('take') take?: number) {
  return this.notesService.findAll({ skip, take });
}

// src/modules/notes/dto/create-note.dto.ts
import { IsString, IsNotEmpty, MaxLength } from 'class-validator';

export class CreateNoteDto {
  @IsString()
  @IsNotEmpty()
  @MaxLength(200)
  title: string;

  @IsString()
  content?: string;
}

app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,      // 自动剥离 DTO 上没有声明的字段（防注入额外字段）
    transform: true,      // 把普通对象转成 DTO 类实例，并按类型转换
    forbidNonWhitelisted: true, // 出现未声明字段直接报错
  }),
);

import { PartialType } from '@nestjs/swagger'; // 或 @nestjs/mapped-types
export class UpdateNoteDto extends PartialType(CreateNoteDto) {}

// notes.schema.ts
import { z } from 'zod';

// 请求 schema —— 校验进来的 body
export const createNoteSchema = z.object({
  title: z.string().min(1).max(200),
  content: z.string().optional(),
});
export type CreateNote = z.infer<typeof createNoteSchema>;  // 类型从 schema 推导，不手写

// 响应 schema —— 给返回数据定型
export const noteSchema = z.object({
  id: z.number().int(),
  title: z.string(),
  content: z.string(),
  createdAt: z.string(),
});
export type Note = z.infer<typeof noteSchema>;

export const updateNoteSchema = createNoteSchema.partial();               // 全部可选
export const patchTitleSchema  = createNoteSchema.pick({ title: true });  // 只取部分字段
export const withAuthorSchema  = createNoteSchema.extend({ authorId: z.number().int() }); // 扩展

// src/common/pipes/zod-validation.pipe.ts
import { PipeTransform, Injectable, BadRequestException } from '@nestjs/common';
import { ZodSchema } from 'zod';

@Injectable()
export class ZodValidationPipe<T> implements PipeTransform<T> {
  constructor(private schema: ZodSchema<T>) {}

  transform(value: unknown): T {
    const result = this.schema.safeParse(value);
    if (!result.success) {
      throw new BadRequestException(result.error.flatten().fieldErrors); // 字段级错误
    }
    return result.data; // 已校验、已转型，类型为 T
  }
}

import { createNoteSchema, CreateNote } from './notes.schema';
import { ZodValidationPipe } from '../../common/pipes/zod-validation.pipe';

const CreateNotePipe = new ZodValidationPipe(createNoteSchema);

@Post()
create(@Body(CreateNotePipe) body: CreateNote) {
  return this.notes.create(body); // body 已被 schema 校验过
}

import { createZodDto } from 'nestjs-zod';
import { createNoteSchema } from './notes.schema';

export class CreateNoteDto extends createZodDto(createNoteSchema) {}
// 配合全局 ZodValidationPipe，Controller 写法退回到 @Body() body: CreateNoteDto

// 前端：react-hook-form 用 zodResolver 跑同一套校验规则
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { createNoteSchema, CreateNote } from '@my/schemas';

const { register, handleSubmit } = useForm<CreateNote>({
  resolver: zodResolver(createNoteSchema), // ★ 前端校验规则 = 后端，同一个 schema 对象
});

// src/modules/notes/notes.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class NotesService {
  constructor(private readonly notesRepository: NotesRepository) {}

  create(dto: CreateNoteDto) { /* 业务规则 */ }
}

@Module({
  controllers: [NotesController],
  providers: [NotesService, NotesRepository],
})
export class NotesModule {}

providers: [
  { provide: NotesService, useClass: NotesService },
]

{ provide: 'CONFIG', useValue: { pageSize: 20 } }

// 注入非类 token 时用 @Inject
constructor(@Inject('CONFIG') config: { pageSize: number }) {}

@Injectable()
export class AuthGuard implements CanActivate {
  constructor(private readonly reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const req = context.switchToHttp().getRequest();
    return !!req.user;     // 没登录就拦截
  }
}

@UseGuards(AuthGuard)
@Get('profile')
getProfile() { ... }

@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) { ... }
// id 在进入方法体前已被转成 number，非数字直接抛 400

@Injectable()
export class IntRangePipe implements PipeTransform {
  transform(value: number) {
    if (value < 0) throw new BadRequestException('必须为正数');
    return value;
  }
}

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler) {
    const now = Date.now();
    return next
      .handle()                     // 返回的是 Observable，不是直接结果
      .pipe(tap(() => console.log(`耗时 ${Date.now() - now}ms`)));
  }
}

throw new NotFoundException('笔记不存在');
// 自动响应: 404 { statusCode: 404, message: "笔记不存在", error: "Not Found" }

@Catch(BusinessError)
export class BusinessFilter implements ExceptionFilter {
  catch(exception: BusinessError, host: ArgumentsHost) {
    const res = host.switchToHttp().getResponse();
    res.status(200).json({ code: exception.code, message: exception.message });
  }
}

@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log(`${req.method} ${req.url}`);
    next();
  }
}

export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer) {
    consumer.apply(LoggerMiddleware).forRoutes('notes');
  }
}

@Injectable() 执行
-> 调用 Reflect.defineMetadata('nest:injectable', ..., NotesService)
-> 把"可被容器管理"的标记挂在 NotesService 上

Nest 实例化 NotesController 时
-> Reflect.getMetadata('design:paramtypes', NotesController)
-> 读出 [NotesRepository]  （编译期自动写入的构造参数类型）
-> 去容器里找 NotesRepository 对应的实例
-> 注入到构造函数

const roles = this.reflector.get<string[]>('roles', context.getHandler());

export const Roles = (...roles: string[]) => SetMetadata('roles', roles);

@Controller('notes')
export class NotesController {
  private service: NotesService;

  constructor() {
    const repo = new NotesRepository();   // 装配责任泄漏到了控制器
    this.service = new NotesService(repo);
  }
}

constructor(private readonly notesService: NotesService) {}

@Controller('notes')
export class NotesController {
  constructor(private readonly foo: SomePlainClass) {}  // SomePlainClass 没登记、没 @Injectable
}

Error: Nest can't resolve dependencies of the NotesController (SomePlainClass, ?).
Please make sure that the argument SomePlainClass at index [0] is available in the current context.

实例化 NotesController
-> 读取 design:paramtypes = [NotesService]
-> 发现构造参数依赖 NotesService
-> 实例化 NotesService
   -> 读取 design:paramtypes = [NotesRepository]
   -> 发现构造参数依赖 NotesRepository
   -> 实例化 NotesRepository（叶子节点，无依赖）
   -> 用它构造 NotesService
-> 用 NotesService 构造 NotesController

const moduleRef = await Test.createTestingModule({
  controllers: [NotesController],
  providers: [
    NotesService,
    { provide: NotesRepository, useValue: { findAll: jest.fn() } }, // mock 替身
  ],
}).compile();

const controller = moduleRef.get(NotesController);

NestFactory.create(AppModule)
  -> DependenciesScanner 扫描 imports 树
  -> Container 建立模块图（每个模块的 providers / controllers / exports / imports）
  -> InstanceLoader 按拓扑序实例化
     -> 叶子 provider 先建，依赖它们的后建
  -> 所有 controller / provider 就绪
  -> 路由表从 controller 的 @Get/@Post 元数据生成
  -> app.listen() 开始接请求

请求进入
-> 1. Middleware              （能拿 req/res/next，能提前结束）
-> 2. Guard                    （鉴权，false 即拦截）
-> 3. Interceptor（前置）       （方法执行前）
-> 4. Pipe                     （参数转换 / 校验）
-> 5. Controller 方法          （业务，调用 service）
-> 6. Interceptor（后置）       （能改返回值）
-> 响应返回

-> Exception Filter           （按 @Catch 匹配的过滤器接住，转成响应）

try {
  response = run(handler, pipes, interceptors, ...);
} catch (e) {
  for (const filter of filtersFromOutsideIn) {
    if (filter.catches(e)) return filter.handle(e);
  }
  // 兜底：HttpException 走默认映射，其它统一 500
}

// main.ts
app.useGlobalFilters(new AllExceptionsFilter());

1. 所有模块实例化完成
2. onModuleInit()        —— 实现 OnModuleInit 的 provider 在此被调用
3. onApplicationBootstrap() —— 实现 OnApplicationBootstrap 的 provider 被调用
4. app.listen()，开始接请求
...
5. 收到关闭信号
6. onModuleDestroy()     —— 实现 OnModuleDestroy 的 provider 被调用
7. onApplicationShutdown()

app.enableShutdownHooks(); // 监听 SIGINT/SIGTERM，触发上面的 destroy 钩子

// tsconfig.json
{
  "compilerOptions": {
    "experimentalDecorators": true,   // 旧版装饰器规范（TC39 Stage 2，已被推翻重做）
    "emitDecoratorMetadata": true     // 把类型信息写进元数据；只对旧装饰器有效
  }
}

@injectable()
class NotesService {}

// 等价于：
class NotesService {}
NotesService = injectable()(NotesService);   // 装饰器就是个接收类、返回（可能改造过的）类的函数

function log(target, propertyKey, descriptor: PropertyDescriptor) {
  const orig = descriptor.value;                  // descriptor.value 就是原方法
  descriptor.value = function (...args) {
    console.log(`调用 ${propertyKey}`);           // 前置逻辑
    return orig.apply(this, args);                // 再调原方法（apply 保住 this）
  };
}

class NotesService {
  @log                                            // 等价于：log(类原型, 'findAll', 方法描述符)
  findAll() { return [...]; }
}

{
  value: [Function: findAll],   // 那个方法函数本身
  writable: true,               // 能否重新赋值
  enumerable: false,            // 是否出现在 for...in
  configurable: true,           // 能否删除 / 改配置
}

class Foo {
  constructor(@Inject('DB') db: Db, logger: Logger) {}
  //          ↑ 第 1 步：先执行 Inject('DB')，返回内层函数
  //                        ↑ 第 2 步：用内层函数去装饰“第 0 个参数”（db）
}

function Inject(token: string) {
  return (target, propertyKey, parameterIndex) => {   // ← 这才是真装饰器
    // target = Foo（构造函数参数的 target 是类本身）
    // propertyKey = undefined（构造函数参数没有具体方法名）
    // parameterIndex = 0（db 是第 0 个参数；logger 会是 1）
    Reflect.defineMetadata('inject:' + parameterIndex, token, target);
    // ↑ 记一条元数据：“第 0 个参数要注入 token='DB'”
  };
}

function log(value, context: DecoratorContext) {
  // context = { kind: 'method'|'class'|..., name, addInitializer, ... }
  // 不再改 descriptor，而是返回一个"替换"，或用 context.addInitializer 注册初始化逻辑
}

// @Module()：把传入的 { providers, controllers, imports, exports } 整个贴到类上
export const Module = (metadata: ModuleMetadata): ClassDecorator =>
  (target) => {
    Reflect.defineMetadata('nest:module', metadata, target);
  };

// @Controller()：贴两个标签——"我是 controller" + 路由前缀
export const Controller = (prefix = ''): ClassDecorator =>
  (target) => {
    Reflect.defineMetadata('nest:controller', true, target);
    Reflect.defineMetadata('nest:path', prefix, target);
  };

// @Injectable()：贴"我是可注入 provider"的标签
export const Injectable = (): ClassDecorator =>
  (target) => {
    Reflect.defineMetadata('nest:injectable', true, target);
  };

export const Body = () =>
  (target, propertyKey, parameterIndex) => {       // ← 参数装饰器签名：(target, key, index)
    Reflect.defineMetadata('nest:param', { index: parameterIndex, type: 'body' }, target, propertyKey);
  };

@Injectable()
class NotesService {
  constructor(private repo: NotesRepository, private logger: Logger) {}
}
// emitDecoratorMetadata 让 TS 编译出：
//   __metadata("design:paramtypes", [NotesRepository, Logger])
// → Reflect.defineMetadata 把 [NotesRepository, Logger] 贴到 NotesService 上