NestJS 源码架构分析
源码版本：NestJS 10.x，仓库
github.com/nestjs/nest
本地路径：~/document/nestskill/.hermes/tmp/nestjs-source/
文档参照：~/document/nestskill/.hermes/tmp/nestjs-docs/md/
一、整体架构
1.1 架构总览图
┌──────────────────────────────────────────────┐
│ 用户代码 │
│ main.ts → NestFactory.create(AppModule) │
└────────────────────┬─────────────────────────┘
│ ①
┌────────────────────▼─────────────────────────┐
│ packages/common │
│ │
│ ┌──────────┐ ┌───────────┐ ┌─────────┐ │
│ │ Decorators │ │ Interfaces │ │Exceptions│ │
│ │@Controller │ │ CanActivate │ │ BadRequest│ │
│ │@Injectable │ │PipeTransform│ │ NotFound │ │
│ │@Module │ │NestInterceptor│└─────────┘ │
│ │@UseGuards │ │ExceptionFilter│ │
│ │@UsePipes │ │ Scope │ │
│ │@Catch │ │ForwardReference│ │
│ └──────────┘ └───────────┘ │
└────────────────────┬─────────────────────────┘
│ ② 框架依赖 common
┌────────────────────▼─────────────────────────┐
│ packages/core │
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ NestFactoryStatic │ │
│ │ create() / createMicroservice() / │ │
│ │ createApplicationContext() │ │
│ └──────────────┬───────────────────────────┘ │
│ │ ③ │
│ ┌────────────┴────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌─────────────────────┐ │
│ │ NestContainer │ │ ApplicationConfig │ │
│ │ │ │ global Guards/ │ │
│ │ ModulesContainer│ │ Pipes/Interceptors│ │
│ │ Map<token, │ │ /Filters │ │
│ │ Module> │ └─────────────────────┘ │
│ │ │ │
│ │ ┌──────────┐│ │
│ │ │ Module ││ ┌──────────────────────┐ │
│ │ │ _providers│ │ DependenciesScanner │ │
│ │ │ _injectables│ │ scan() — 扫描模块 │ │
│ │ │ _controllers│ │ classify() — 分类 │ │
│ │ │ _imports ││ │ applyApplication │ │
│ │ │ _exports ││ │ Providers() │ │
│ │ └──────────┘│ └──────────┬───────────┘ │
│ └──────────────┘ │ ④ │
│ ┌──────────────┴────────────┐ │
│ │ InstanceLoader │ │
│ │ createInstancesOfDepend... │ │
│ └──────────────┬────────────┘ │
│ ⑤ │
│ ┌──────────────┴────────────┐ │
│ │ Injector │ │
│ │ resolveSingleDependencies │ │
│ │ instantiateClass() │ │
│ │ resolvePropertyDeps() │ │
│ └──────────────┬────────────┘ │
│ ⑥ │
│ ┌──────────────┴────────────┐ │
│ │ InstanceWrapper │ │
│ │ values: WeakMap<ContextId,│ │
│ │ InstancePerContext│ │
│ │ scope: SINGLETON|REQUEST │ │
│ │ |TRANSIENT │ │
│ └──────────────────────────┘ │
└─────────────────────┬───────────────────────┘
│
┌──────────────────────▼───────────────────────┐
│ NestApplication │
│ (extends NestApplicationContext) │
│ │
│ ┌────────────────────────────────────────┐ │
│ │ RoutesResolver.resolve() │ │
│ │ ↓ │ │
│ │ RouterExplorer.registerRoute() │ │
│ │ ↓ │ │
│ │ httpAdapter.use / .get / .post ... │ │
│ └────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────┐ │
│ │ MicroservicesModule (optional) │ │
│ │ SocketModule (optional) │ │
│ └────────────────────────────────────────┘ │
│ │
│ ┌────────────────────────────────────────┐ │
│ │ Request Lifecycle (per request) │ │
│ │ │ │
│ │ ① MiddlewareModule │ │
│ │ ↓ │ │
│ │ ② GuardsContextCreator │ │
│ │ → canActivate() │ │
│ │ ↓ │ │
│ │ ③ PipesContextCreator │ │
│ │ → transform() │ │
│ │ ↓ │ │
│ │ ④ Controller.handler() │ │
│ │ ↓ │ │
│ │ ⑤ InterceptorsContextCreator │ │
│ │ → intercept() (洋葱模型) │ │
│ │ ↓ │ │
│ │ ⑥ ExceptionsHandler │ │
│ │ → catch() │ │
│ │ ↓ │ │
│ │ ⑦ RouterResponseController │ │
│ │ → applyStatus() / json() │ │
│ └────────────────────────────────────────┘ │
└──────────────────────┬─────────────────────┘
│
┌──────────────────────▼─────────────────────┐
│ AbstractHttpAdapter │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ platform-express │ │ platform-fastify │ │
│ │ ExpressAdapter │ │ FastifyAdapter │ │
│ └──────────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────┘
┌─────────────────────────────────────────────┐
│ 包依赖方向 │
│ common ──► core ──► platform-express │
│ ├──► platform-fastify │
│ ├──► microservices │
│ └──► websockets │
└─────────────────────────────────────────────┘
1.2 架构图分层描述
| 层级 | 组成 | 职责 |
|---|---|---|
| L0 用户代码 | main.ts |
调用 NestFactory.create(AppModule)，传入根模块 |
| L1 common | 装饰器 / 接口 / 异常类 | 定义所有扩展点契约（CanActivate、PipeTransform 等），不包含任何运行时逻辑 |
| L2 core（框架核心） | NestFactory / NestContainer / Injector / Scanner | 启动时：扫描模块 → 建立依赖图 → 实例化所有 Provider；运行时：构建请求处理链 |
| L3 应用层 | NestApplication | 持有容器和 HTTP 适配器，完成路由注册和中间件绑定，处理请求生命周期 |
| L4 平台抽象 | Express / Fastify 适配器 | 将框架接口翻译为具体 HTTP 平台 API，实现平台无关性 |
1.3 启动时序 vs 运行时
┌─────────────────────────────────────────────────────────────────────┐
│ 启动阶段（一次性） │
│ │
│ main.ts │
│ │ │
│ ▼ │
│ NestFactory.create() │
│ ├─ new NestContainer() ← IOC 容器（所有模块的存放点） │
│ ├─ new ApplicationConfig() ← 全局 Guard/Pipe/Interceptor/Filter │
│ ├─ DependenciesScanner.scan() ← 递归扫描所有 @Module，建立依赖图 │
│ └─ InstanceLoader.createInstancesOfDependencies() │
│ └─ Injector 递归实例化所有 Provider（拓扑序） │
│ └─ 每个 Provider 包装为 InstanceWrapper │
│ │
│ new NestApplication() │
│ ├─ RoutesResolver.resolve() ← 遍历所有 Controller，注册到 httpAdapter│
│ └─ MiddlewareModule.bind() ← 绑定中间件到 httpAdapter │
└─────────────────────────────────────────────────────────────────────┘
▼ 启动完成，监听端口
┌─────────────────────────────────────────────────────────────────────┐
│ 运行时（每请求） │
│ │
│ HTTP Request → httpAdapter │
│ │ │
│ ├─ MiddlewareModule（按 order 顺序执行，next() 放行） │
│ │ │
│ ├─ Guard 链（GuardsContextCreator → guardsConsumer） │
│ │ │
│ ├─ Pipe 链（PipesContextCreator → pipesConsumer） │
│ │ └─ 参数解析：@Body / @Query / @Param → transform() │
│ │ │
│ ├─ Controller.handler()（业务逻辑） │
│ │ │
│ ├─ Interceptor 链（InterceptorsContextCreator → interceptorsConsumer）│
│ │ └─ 洋葱模型：最后注册的 Interceptor 最先执行 handle() │
│ │ │
│ └─ 正常路径：RouterResponseController → httpAdapter 响应 │
│ 异常路径：ExceptionsHandler → catch() → httpAdapter 响应 │
└─────────────────────────────────────────────────────────────────────┘
二、应用启动流程（NestFactory）
源码：packages/core/nest-factory.ts（NestFactoryStatic.create()）
2.1 启动序列
NestFactory.create(module, options)
├── new NestContainer() // 创建 IOC 容器
├── new ApplicationConfig() // 全局配置（全局 Guard/Pipe/Interceptor/Filter）
├── new GraphInspector() // 依赖图序列化（snapshot 模式）
├── NestFactoryStatic.initialize()
│ ├── DependenciesScanner.scan() // 扫描所有模块、Controller、Provider
│ │ └── 遍历 @Module() 的 imports/providers/controllers/exports
│ │ 将类按 @Controller() / @Injectable() / @Module() 分类
│ │ 建立模块间依赖图
│ ├── InstanceLoader.createInstancesOfDependencies()
│ │ └── Injector 解析依赖树，实例化所有 Provider
│ └── DependenciesScanner.applyApplicationProviders()
│ └── 处理 APP_GUARD / APP_PIPE / APP_INTERCEPTOR / APP_FILTER
└── new NestApplication(container, httpAdapter, config)
├── RoutesResolver.resolve() // 将路由注册到 HTTP 适配器
└── MiddlewareModule.bind() // 绑定中间件
2.2 三个入口方法
| 方法 | 产物 | HTTP | 微服务 | 说明 |
|---|---|---|---|---|
NestFactory.create() |
NestApplication |
✅ | ❌ | 标准 HTTP 应用 |
NestFactory.createMicroservice() |
NestMicroservice |
❌ | ✅ | 纯微服务（gRPC/AMQP/Kafka） |
NestFactory.createApplicationContext() |
NestApplicationContext |
❌ | ❌ | 无 HTTP（脚本/CRON） |
2.3 关键类说明
NestContainer（packages/core/injector/container.ts）
- 持有
ModulesContainer（Map<token, Module>），存储所有已编译模块 - 持有
globalModulesSet，全局模块（@Global()）会被注入到每个模块 - 持有
internalProvidersStorage，内置提供者（Logger/APP_*/REQUEST 等）
DependenciesScanner（packages/core/scanner.ts）
- 从入口模块递归扫描
imports，构建完整模块列表 - 通过
MetadataScanner读取类上的reflectMetadata：@Controller()→ 加入Module._controllers@Injectable()→ 加入Module._providers或_injectables@Module()→ 识别模块元数据
- 将
APP_GUARD/APP_PIPE/APP_INTERCEPTOR/APP_FILTER收集到ApplicationConfig
InstanceLoader（packages/core/injector/instance-loader.ts）
- 遍历
NestContainer中所有模块 - 对每个模块的
_providers调用injector.load()实例化
三、IOC 容器（依赖注入）
3.1 核心数据结构
InstanceWrapper（packages/core/injector/instance-wrapper.ts）
export class InstanceWrapper<T = any> {
public readonly token: InjectionToken; // provider 的 token（类名或字符串）
public scope?: Scope = Scope.DEFAULT; // SINGLETON / REQUEST / TRANSIENT
public metatype: Type<T> | Function | null; // 原始类
public readonly values = new WeakMap<ContextId, InstancePerContext<T>>();
// ^^^^^^^^^^^^^^^^^^^ 关键：按 ContextId 存储实例
// SINGLETON → 始终用 STATIC_CONTEXT（全局唯一实例）
// REQUEST → 每个请求一个新 ContextId
// TRANSIENT → 每个注入点一个新 ContextId
}
Module（packages/core/injector/module.ts）
export class Module {
private readonly _providers = new Map<InjectionToken, InstanceWrapper>(); // @Injectable
private readonly _injectables = new Map<InjectionToken, InstanceWrapper>(); // 注入到其他类的
private readonly _controllers = new Map<InjectionToken, InstanceWrapper<Controller>>();
private readonly _middlewares = new Map<InjectionToken, InstanceWrapper<Injectable>>();
private readonly _imports = new Set<Module>(); // 被导入的子模块
private readonly _exports = new Set<InjectionToken>(); // 导出给其他模块的 token
}
3.2 Injector 解析流程
源码：packages/core/injector/injector.ts
// 注入器的核心方法：resolveSingleDependencies(token, wrapper)
private async resolveSingleDependencies<T>(
wrapper: InstanceWrapper<T>,
module: Module,
contextId: ContextId,
): Promise<InstancePerContext<T>> {
// 1. 从构造函数参数读取 token 列表（reflect PARAMTYPES_METADATA）
const dependencies = this.resolveDependencies(wrapper, module);
// 2. 遍历参数，递归解析每个依赖
for (const [index, dependency] of dependencies.entries()) {
const dependentWrapper = await this.resolveComponent(
module, dependency.token, wrapper.walkableDependencies, ...);
// 递归调用 resolveSingleDependencies（可能出现循环，此时返回 forwardRef）
}
// 3. 实例化（useFactory / useClass / new metatype(...dependencies)）
const instance = this.instantiateClass(wrapper, dependencies);
// 4. 属性注入（@Inject() 属性装饰器）
this.resolvePropertyDependencies(wrapper, instance, module);
return { instance, isResolved: true };
}
3.3 Provider 作用域（Scope）
| Scope | 行为 | 使用场景 |
|---|---|---|
SINGLETON（默认） |
全进程唯一实例，values 用 STATIC_CONTEXT |
绝大多数 Provider |
REQUEST |
每个请求一个实例，请求结束销毁 | 数据库连接、用户认证信息 |
TRANSIENT |
每个注入点一个实例 | 每处注入都独立 |
3.4 循环依赖处理
@Inject(forwardRef(() => OtherService))→ 将依赖标记为forwardRefModuleCompiler在编译阶段将ForwardReference解析为实际类Injector在遇到未解析 token 时返回UNINITIALIZED标记，延迟到实例化时再解析
3.5 Metadata 常量（装饰器存储位置）
// @nestjs/common/constants.ts
export const PARAMTYPES_METADATA = 'self:paramtypes'; // 构造函数参数类型
export const PROPERTY_DEPS_METADATA = 'self:property:deps'; // 属性注入
export const SCOPE_METADATA = 'self:scope'; // @Injectable({ scope })
export const INJECTABLE_WATERMARK = 'injectable'; // @Injectable() 标记
export const CONTROLLER_WATERMARK = 'controller'; // @Controller() 标记
export const MODULE_METADATA = 'module'; // @Module() 标记
export const GUARDS_METADATA = 'guards'; // @UseGuards()
export const PIPES_METADATA = 'pipes'; // @UsePipes()
export const INTERCEPTORS_METADATA = 'interceptors'; // @UseInterceptors()
export const EXCEPTION_FILTERS_METADATA = 'filters'; // @UseFilters()
四、请求处理链路
4.1 完整请求流程
HTTP Request
│
▼
MiddlewareModule（中间件层）
│ 按 order 顺序执行
│ next() 放行
▼
RoutesResolver.resolve()
└── RouterExplorer.resolveNext() 遍历已注册的路由
│
▼
RouterExecutionContext.create()
│
▼
┌─────────────────────────────────────────┐
│ Guard 链（GuardsContextCreator） │
│ guardsContextCreator.create() │
│ → 合并 [类级 Guard, 方法级 Guard] │
│ → 合并 ApplicationConfig 全局 Guard │
│ → 每个 guard.canActivate() 顺序调用 │
│ → 返回 false → 抛 UnauthorizedException│
└────────────────┬────────────────────────┘
▼
┌─────────────────────────────────────────┐
│ 参数解析 + Pipe（RouterParamsFactory） │
│ @Body/@Query/@Param → 读取原始值 │
│ 每个参数如果有 Pipe → pipe.transform() │
│ PipesContextCreator.create() │
│ → 合并 [类级 Pipe, 方法级 Pipe] │
│ → 合并 ApplicationConfig 全局 Pipe │
└────────────────┬────────────────────────┘
▼
Controller.handler()
(业务逻辑)
│
▼
┌─────────────────────────────────────────┐
│ Interceptor 链 │
│ InterceptorsContextCreator.create() │
│ → 合并 [类级, 方法级, 全局] Interceptor │
│ interceptorsConsumer.intercept() │
│ → 最后一个先执行 .handle()（即业务） │
│ → 其余从外到内包裹（类似洋葱模型） │
└────────────────┬────────────────────────┘
│
┌──────────┴──────────┐
│ 正常响应 │ 异常抛出
▼ ▼
┌─────────────┐ ┌─────────────────────┐
│ RouterProxy │ │ ExceptionsHandler │
│ .applyResult│ │ .next() 异常捕获 │
└─────────────┘ │ → 最近的 Filter │
│ → 全局 Filter │
│ → HttpException │
└─────────────────────┘
4.2 源码链路核心代码
RouterExecutionContext.create()（packages/core/router/router-execution-context.ts:80-174）
public create(instance, callback, methodName, moduleKey, ...) {
// 1. 收集该路由的 Guard / Pipe / Interceptor 元数据
const guards = this.guardsContextCreator.create(instance, callback, moduleKey, ...);
const pipes = this.pipesContextCreator.create(instance, callback, moduleKey, ...);
const interceptors = this.interceptorsContextCreator.create(instance, callback, moduleKey, ...);
// 2. 创建 Guard 校验函数
const fnCanActivate = this.createGuardsFn(guards, instance, callback, contextType);
// 3. 创建 Pipe 参数处理函数
const fnApplyPipes = this.createPipesFn(pipes, paramsOptions);
// 4. 包装 handler：先执行 pipes，再调用业务方法
const handler = (args, req, res, next) => async () => {
fnApplyPipes && (await fnApplyPipes(args, req, res, next)); // 参数转换
return callback.apply(instance, args); // 业务逻辑
};
// 5. 返回最终的路由处理器
return async (req, res, next) => {
fnCanActivate && (await fnCanActivate([req, res, next])); // Guard 校验
const result = await this.interceptorsConsumer.intercept( // Interceptor 包裹
interceptors, [req, res, next], instance, callback,
handler(args, req, res, next), contextType,
);
await fnHandleResponse(result, res, req); // 响应处理
};
}
4.3 ContextCreator 模式（扩展点统一实现）
Guard / Pipe / Interceptor / ExceptionFilter 都有完全对称的 ContextCreator：
packages/core/
├── guards/
│ ├── guards-context-creator.ts # 读取 @UseGuards() 元数据，解析 guard 实例
│ └── guards-consumer.ts # 按序执行 guard.canActivate()
├── pipes/
│ ├── pipes-context-creator.ts # 读取 @UsePipes() 元数据，解析 pipe 实例
│ └── pipes-consumer.ts # 调用 pipe.transform()
├── interceptors/
│ ├── interceptors-context-creator.ts
│ └── interceptors-consumer.ts # 执行 intercept() 链（洋葱模型）
└── exceptions/
├── exceptions-handler.ts # 捕获异常，执行 filter.catch()
└── router-exception-filters.ts # 从元数据创建异常过滤器链
每个 ContextCreator 的 create() 方法做同样的事情：
- 读取类级装饰器元数据（
GUARDS_METADATA等） - 读取方法级装饰器元数据
- 从
moduleRef.injectables中解析实例（getGuardInstance/getPipeInstance） - 从
ApplicationConfig获取全局增强器（getGlobalMetadata） - 合并，返回实例数组
五、模块系统
5.1 模块结构
@Module({
imports: [OtherModule], // 导入其他模块，获取其 exports
providers: [MyService], // 本模块内的 provider（仅本模块可见）
controllers: [MyController], // 本模块内的 controller
exports: [MyService], // 允许其他模块导入的 token
})
export class MyModule {}
5.2 模块编译流程
DependenciesScanner.scan()：
- 从入口模块递归扫描所有
imports - 对每个模块调用
ModuleCompiler.compile()：- 将
DynamicModule/ForwardReference解析为Module类 - 合并
imports中的exports - 检测循环依赖
- 将
- 将
Module实例存入NestContainer.modules
5.3 动态模块（forRoot 模式）
// ConfigModule.forRoot({})
@Module({})
export class ConfigModule {
static forRoot(options: ConfigOptions): DynamicModule {
return {
module: ConfigModule,
global: true, // 可选：全局模块
providers: [
{
provide: CONFIG_OPTIONS, // 自定义 token
useFactory: () => options,
},
],
exports: [CONFIG_OPTIONS],
};
}
}
5.4 RouterModule（懒加载路由）
源码：packages/core/router/router-module.ts
@Module({})
export class RouterModule {
static register(routes: Routes): DynamicModule {
return {
module: RouterModule,
providers: [{ provide: ROUTES, useValue: routes }],
};
}
}
// AppModule 中使用
@Module({
imports: [
RouterModule.register([
{
path: 'admin',
loadChildren: () => import('./admin/admin.module').then(m => m.AdminModule),
// ^^^^^^^^^^^^^^^^^^^ 懒加载：模块在访问时才导入
},
]),
],
})
export class AppModule {}
5.5 全局模块
@Global() 装饰器将模块标记为全局。全局模块的 exports 会自动注入到所有模块的 providers 中，无需在每个模块 imports 里重复声明。
框架内置的全局模块：
InternalCoreModule（Logger, APP_*/REQUEST 提供者）SharedModule（公共工具）
六、平台抽象（HttpAdapter）
6.1 抽象层设计
packages/core/
├── adapters/
│ ├── http-adapter.ts # AbstractHttpAdapter 接口
│ └── index.ts # 导出所有适配器
└── nest-application.ts # 使用 httpAdapter 操作 HTTP
packages/platform-express/
└── index.ts # ExpressAdapter implements AbstractHttpAdapter
packages/platform-fastify/
└── index.ts # FastifyAdapter implements AbstractHttpAdapter
AbstractHttpAdapter 核心方法：
abstract class AbstractHttpAdapter {
abstract get(handler, ...args): any; // HTTP GET
abstract post(handler, ...args): any; // HTTP POST
abstract initHttpServer(options): void;
abstract close(): void;
abstract use(...args): any; // 中间件
abstract applyVersioning(options): void; // API 版本控制
}
6.2 NestApplication 的 HTTP 无关性
NestApplication 持有 httpAdapter: AbstractHttpAdapter，它本身不包含任何 Express/Fastify 代码。通过替换适配器，框架可以在不同 HTTP 平台间切换，路由和中间件绑定逻辑保持不变。
七、关键设计模式
7.1 ContextCreator 模式
每个扩展点（Guard/Pipe/Interceptor/Filter）都有 XxxContextCreator + XxxConsumer 两个类：
- ContextCreator：从元数据和容器中收集、实例化扩展点
- Consumer：执行扩展点（顺序执行 Guard，返回 boolean；顺序执行 Pipe 做参数转换；Interceptors 链式执行）
7.2 InstanceWrapper 模式
所有 Provider 都被 InstanceWrapper 包装，values 用 WeakMap<ContextId, InstancePerContext> 实现作用域隔离：
- SINGLETON：一个
STATIC_CONTEXTkey，进程唯一 - REQUEST：每个请求一个新
ContextId，请求结束销毁 - TRANSIENT：每个注入点一个
ContextId
7.3 Metadata Symbol 存储
所有装饰器元数据通过 Reflect.getMetadata / Reflect.defineMetadata 存储在类的原型上，key 是字符串常量。框架不修改类，只读写元数据。
7.4 ExceptionZone
NestFactory.createProxy() 通过 Proxy 包装所有实例方法，所有方法调用都在 ExceptionsZone.run() 内执行，异常被统一捕获并格式化输出，防止未处理异常导致进程崩溃。
八、与官方文档的对照
| 官方文档章节 | 源码对应 |
|---|---|
fundamentals/di.md |
packages/core/injector/injector.ts |
fundamentals/modules.md |
packages/core/injector/module.ts |
fundamentals/lifecycle-events.md |
packages/core/hooks/ |
fundamentals/dynamic-modules.md |
packages/core/injector/（DynamicModule 支持在 scanner 和 module 中） |
fundamentals/circular-dependency.md |
packages/core/injector/injector.ts + forwardRef() |
fundamentals/dynamic-modules.md |
packages/core/injector/module.ts 的 forRootAsync() |
fundamentals/injection-scopes.md |
packages/core/injector/instance-wrapper.ts 的 scope |
interceptors.md |
packages/core/interceptors/ |
guards.md |
packages/core/guards/ |
pipes.md |
packages/core/pipes/ |
exception-filters.md |
packages/core/exceptions/ |
middlewares.md |
packages/core/middleware/ |
techniques/serialization.md |
packages/common/serializer/ |
security/cors.md |
packages/core/nest-application.ts 的 enableCors() |
techniques/versioning.md |
packages/core/router/ + packages/common/decorators/http/ 的 @Version() |
九、目录结构速查
9.1 packages/core/
packages/core/
├── nest-factory.ts # 启动入口（NestFactoryStatic）
├── nest-application.ts # HTTP 应用（extends NestApplicationContext）
├── nest-application-context.ts # 无 HTTP 应用上下文（createApplicationContext）
├── application-config.ts # 全局配置（global Guards/Pipes/Interceptors/Filters）
├── scanner.ts # DependenciesScanner — 递归扫描 @Module，建立依赖图
├── metadata-scanner.ts # MetadataScanner — 读取类原型上的反射元数据
│
├── injector/ # IOC 容器核心
│ ├── injector.ts # Injector — 依赖解析 + 实例化（resolveSingleDependencies）
│ ├── container.ts # NestContainer — 所有模块的存储（Map<token, Module>）
│ ├── module.ts # Module — 单模块的 _providers / _controllers / _imports / _exports
│ ├── instance-wrapper.ts # InstanceWrapper — 单实例包装 + WeakMap<ContextId> 作用域
│ ├── instance-loader.ts # InstanceLoader — 触发所有模块实例化
│ ├── modules-container.ts # ModulesContainer — Map 实现，存储 token→Module
│ ├── compiler.ts # ModuleCompiler — 将 DynamicModule / ForwardReference 编译为 Module
│ ├── helpers/
│ │ └── provider-classifier.ts # 区分 useClass / useFactory / useValue Provider
│ ├── internal-core-module/ # 内核核心模块（Logger / APP_* / REQUEST Provider）
│ ├── inquirer/ # 记录当前正在解析的依赖（循环检测）
│ ├── lazy-module-loader/ # 懒加载模块（RouterModule 懒加载子模块）
│ └── opaque-key-factory/ # 模块 token 生成策略（random / shallow / deep-hash）
│
├── router/ # 路由系统
│ ├── routes-resolver.ts # RoutesResolver — 遍历模块的 controllers，注册路由到 httpAdapter
│ ├── router-module.ts # RouterModule — 懒加载路由（register() / registerRouted())
│ ├── router-explorer.ts # RouterExplorer — 遍历 controller 方法，构造路由处理器
│ ├── router-execution-context.ts # RouterExecutionContext — 构建 Guard/Pipe/Interceptor 链
│ ├── router-exception-filters.ts # RouterExceptionFilters — 为每条路由创建异常过滤器链
│ ├── router-proxy.ts # RouterProxy — 统一路由处理包装（异常转发）
│ ├── router-response-controller.ts # RouterResponseController — 响应状态码 / json / redirect
│ ├── route-path-factory.ts # RoutePathFactory — 根据 @Controller/@Version 生成路径模板
│ ├── route-params-factory.ts # RouteParamsFactory — 解析 @Body/@Query/@Param 元数据
│ ├── paths-explorer.ts # PathsExplorer — 扫描 controller 上的路由路径
│ └── request/
│ └── request-constants.ts # REQUEST token（request-scoped 实例的 key）
│
├── guards/ # Guard 扩展点
│ ├── guards-context-creator.ts # GuardsContextCreator — 读取 @UseGuards()，解析 guard 实例
│ ├── guards-consumer.ts # GuardsConsumer — 顺序执行 guard.canActivate()
│ └── index.ts
│
├── pipes/ # Pipe 扩展点
│ ├── pipes-context-creator.ts # PipesContextCreator — 读取 @UsePipes()，解析 pipe 实例
│ ├── pipes-consumer.ts # PipesConsumer — 调用 pipe.transform() 做参数转换
│ ├── params-token-factory.ts # ParamsTokenFactory — 解析 @Body/@Query/@Param token
│ └── index.ts
│
├── interceptors/ # Interceptor 扩展点
│ ├── interceptors-context-creator.ts
│ └── interceptors-consumer.ts # InterceptorsConsumer — 洋葱模型执行
│
├── exceptions/ # ExceptionFilter 扩展点
│ ├── exceptions-handler.ts # ExceptionsHandler — 捕获异常，执行 filter.catch() 链
│ ├── base-exception-filter-context.ts # BaseExceptionFilterContext — 基类
│ ├── base-exception-filter.ts # BaseExceptionFilter — 基类过滤器
│ ├── external-exception-filter-context.ts
│ ├── external-exception-filter.ts # ExternalExceptionFilter — 最后兜底的 HttpException 处理器
│ ├── external-exceptions-handler.ts # ExternalExceptionsHandler — 微服务异常处理
│ └── index.ts
│
├── middleware/ # 中间件（NestJS 风格）
│ ├── middleware-module.ts # MiddlewareModule — 注册 + 按 order 顺序执行
│ ├── container.ts # MiddlewareContainer — 存储中间件实例
│ ├── resolver.ts # MiddlewareResolver — 解析中间件依赖关系
│ ├── builder.ts # MiddlewareBuilder — 中间件链式构建
│ ├── routes-mapper.ts # RoutesMapper — 映射路由到中间件
│ ├── route-info-path-extractor.ts # RouteInfoPathExtractor — 路由信息路径提取
│ └── utils.ts
│
├── helpers/
│ ├── context-creator.ts # ContextCreator — 基类，所有 *ContextCreator 的公共逻辑
│ ├── execution-context-host.ts # ExecutionContextHost — ExecutionContext 实现
│ ├── context-utils.ts # ContextUtils — 参数反射工具（mergeParamsMetatypes 等）
│ ├── handler-metadata-storage.ts # HandlerMetadataStorage — 缓存路由元数据
│ ├── barrier.ts # Barrier — 循环依赖检测屏障
│ ├── load-adapter.ts # 动态加载 platform-express / platform-fastify
│ ├── context-id-factory.ts # ContextIdFactory — 生成 REQUEST scope 的 ContextId
│ ├── external-context-creator.ts # ExternalContextCreator — 微服务/Microservice 上下文创建
│ ├── external-proxy.ts # ExternalProxy — 微服务方法调用的代理包装
│ ├── http-adapter-host.ts # HttpAdapterHost — 平台适配器宿主
│ ├── router-method-factory.ts # RouterMethodFactory — HTTP 方法构造（get/post/put…）
│ ├── messages.ts # 框架内部提示消息
│ ├── rethrow.ts # rethrow — 统一异常重抛
│ ├── interfaces/ # helpers 目录下的接口定义
│ └── ...
│
├── discovery/ # 元数据发现（用于 @nestjs/core 外暴露）
│ └── discovery-service.ts
│
├── inspector/ # 依赖图检查（snapshot 模式）
│ ├── graph-inspector.ts # GraphInspector — 收集依赖关系，生成 SerializedGraph
│ ├── serialized-graph.ts # SerializedGraph — 循环依赖检测和序列化
│ └── noop-graph-inspector.ts # NoopGraphInspector — 默认空实现（snapshot=false）
│
├── services/ # 内置服务
│ └── repl/ # REPL 模式（nest repl 命令）
9.2 packages/common/
packages/common/
├── constants.ts # 所有元数据 key 常量（GUARDS_METADATA / PIPES_METADATA 等）
├── decorators/
│ ├── core/ # @Module / @Injectable / @UseGuards / @UsePipes
│ │ ├── module.decorator.ts # @Global()
│ │ ├── use-guards.decorator.ts # @UseGuards(...guards)
│ │ ├── use-pipes.decorator.ts # @UsePipes(...pipes)
│ │ ├── use-interceptors.decorator.ts
│ │ ├── exception-filters.decorator.ts # @UseFilters(...filters)
│ │ ├── set-metadata.decorator.ts # @SetMetadata(key, value)
│ │ ├── inject.decorator.ts # @Inject(token) / @Optional()
│ │ ├── dependencies.decorator.ts # @Dependencies(...tokens)
│ │ ├── apply-decorators.ts # applyDecorators(...decorators)
│ │ └── catch.decorator.ts # @Catch(...exceptionTypes)
│ ├── http/
│ │ ├── request-mapping.decorator.ts # @Get/@Post/@Put/@Delete/@Patch/@All/@Head/@Options
│ │ ├── route-params.decorator.ts # @Body/@Query/@Param/@Headers/@Request/@Response
│ │ ├── http-code.decorator.ts # @HttpCode(status)
│ │ ├── header.decorator.ts # @Header(name, value)
│ │ ├── redirect.decorator.ts # @Redirect(url, status)
│ │ └── sse.decorator.ts # @Sse()
│ └── modules/
│ └── global.decorator.ts # @Global()
├── interfaces/
│ ├── features/ # CanActivate / NestInterceptor / PipeTransform / ExceptionFilter
│ │ └── execution-context.interface.ts # ExecutionContext / ArgumentsHost
│ ├── modules/ # Provider 类型（ClassProvider / FactoryProvider / ValueProvider / ExistingProvider）
│ │ └── injection-token.interface.ts # InjectionToken
│ ├── hooks/ # OnModuleInit / OnModuleDestroy / OnApplicationBootstrap / BeforeApplicationShutdown / OnApplicationShutdown
│ └── controllers/ # Controller / Headers / Paramtype
├── pipes/ # 内置管道
│ ├── validation.pipe.ts # ValidationPipe（class-validator 集成）
│ ├── parse-int.pipe.ts # ParseIntPipe
│ ├── parse-uuid.pipe.ts # ParseUUIDPipe
│ ├── default-value.pipe.ts # DefaultValuePipe
│ └── ...
├── exceptions/ # HTTP 异常类
│ ├── http.exception.ts # HttpException 基类
│ ├── bad-request.exception.ts # BadRequestException
│ ├── unauthorized.exception.ts # UnauthorizedException
│ ├── forbidden.exception.ts # ForbiddenException
│ ├── not-found.exception.ts # NotFoundException
│ └── ...
└── services/
├── logger.service.ts # Logger
└── console-logger.service.ts # ConsoleLogger
9.3 packages/microservices/
packages/microservices/
├── microservices-module.ts # MicroservicesModule — 承载所有微服务传输层
├── listeners-controller.ts # ListenersController — 消息事件分发
├── container.ts # MicroservicesContainer — 存储所有微服务实例
├── nest-microservice.ts # NestMicroservice — 微服务应用（extends NestApplicationContext）
├── listener-metadata-explorer.ts # ListenerMetadataExplorer — 扫描 @EventPattern/@MessagePattern
├── client/ # ClientProxy — 客户端代理（@Client()）
│ ├── client-kafka.ts
│ ├── client-mqtt.ts
│ ├── client-nats.ts
│ ├── client-redis.ts
│ ├── client-rmq.ts
│ └── client-grpc.ts
├── server/
│ ├── server.ts # Server 基类
│ ├── server-factory.ts # ServerFactory — 创建各传输层服务器
│ ├── server-tcp.ts # TCP
│ ├── server-redis.ts # Redis
│ ├── server-grpc.ts # gRPC
│ ├── server-kafka.ts # Kafka
│ ├── server-nats.ts # NATS
│ ├── server-mqtt.ts # MQTT
│ └── server-rmq.ts # RabbitMQ
├── ctx-host/ # 微服务上下文（MicroserviceContextCreator）
├── deserializers/ # 请求/响应反序列化
├── events/ # 事件相关
├── decorators/ # @EventPattern / @MessagePattern / @Client
├── helpers/ # helpers（grpc-helpers / json-socket / tcp-socket 等）
├── external/ # 外部调用封装
├── factories/ # 工厂类
├── record-builders/ # 消息记录构建器
├── serializers/ # 序列化器
├── enums/ # 微服务相关枚举
├── errors/ # 微服务错误类
├── interfaces/ # 微服务接口定义
└── utils/ # 工具函数
---
## 十、核心要点总结
1. **IOC 容器 = NestContainer（所有模块） + Injector（解析 + 实例化） + InstanceWrapper（实例隔离）**
2. **启动流程**：扫描 → 建立依赖图 → 递归实例化（拓扑排序处理循环依赖）
3. **请求链路**：Middleware → Guard → Pipe → Controller → Interceptor → ExceptionFilter
4. **ContextCreator 模式**：每个扩展点统一使用 元数据读取 → 实例解析 → 全局合并 → Consumer执行
5. **作用域隔离**：InstanceWrapper.values WeakMap，按 ContextId 区分实例生命周期
6. **平台无关**：AbstractHttpAdapter 抽象了 Express/Fastify，NestApplication 本身不含 HTTP 框架代码
7. **装饰器即元数据**：`@Controller()` / `@UseGuards()` 等仅在类原型上存储元数据，框架运行时通过 `Reflect.getMetadata` 读取，不修改类行为
浙公网安备 33010602011771号