工作原理

没有猴子补丁，没有运行时代理：只是恰到好处的时机，加上 Reflect 元数据。

整体流程

DocfyModule.forRoot() 在 NestFactory.create() 阶段同步运行，早于 SwaggerModule.createDocument() 的调用。它用 require() 加载每一个 companion docs 文件，这会执行 docs()，并把 Reflect 元数据直接写到控制器的方法上，效果和 TypeScript 装饰器语法在类定义时做的事完全一样。

等到 SwaggerModule.createDocument() 开始扫描元数据时，一切都已经就位。没有猴子补丁，没有运行时代理。

时机

关键的时机点

onModuleInit 等生命周期钩子，触发时机都晚于 main.ts 中已经调用过的 SwaggerModule.createDocument()。任何基于 onModuleInit 的方案都会得到一份空的 Swagger 文档。这就是为什么 nestjs-docfy 避开了这条路，改用 forRoot() 内部一次同步的 require()，它运行在 NestFactory.create() 期间，早于任何生命周期钩子或 SwaggerModule 调用。

CLI：静态分析

generate CLI 使用 ts-morph 做静态分析：它读取 TypeScript AST，不执行任何项目代码。所有用户提供的路径和 glob 模式在使用前都会先校验和清洗。