先给结论Rfclt 这类方案真正改变的不是“TypeScript 有没有类型”而是“类型信息在程序运行后还留不留在那里”。如果你正在做接口入参校验、RPC 参数解析、ORM 实体映射或者想给低代码平台生成表单定义这篇文章值得读完。过去要在运行时拿到 TypeScript 类型信息绝大多数人第一反应是打开emitDecoratorMetadata配合reflect-metadata在装饰器里读取design:type。这条路能跑但坑很多依赖实验性装饰器语法、类型覆盖不全、泛型信息丢失、还把编译配置和框架深度耦合。TS 7.0 把编译器切换到原生实现之后运行时类型元数据有了新的解法Rfclt 就是在“不靠 emitDecoratorMetadata”这个前提下出现的代表方向之一。这篇文章我会先解释运行时类型元数据到底解决什么问题再对比传统方案为什么让人头疼然后拆解 Rfclt 的设计思路最后用一个最小可运行示例演示“无装饰器也能拿到类型元数据”的实现路径。无论 Rfclt 最终 API 怎么演进理解这套思路都能帮你避开很多运行时类型方案的坑。1. 运行时类型元数据到底是什么问题先看一个日常场景。你写了一个登录接口interface LoginRequest { username: string; password: string; rememberMe: boolean; }编译成 JavaScript 之后接口类型会完全擦除。到了运行阶段后端拿到的只是一个普通对象username是字符串还是数字password是否存在TypeScript 编译器已经管不到了。如果你的服务直接信任外部入参轻则字段缺失重则注入非法数据。解决这个问题有两条路一是写运行时校验层比如手写if判断或者引入 zod、valibot 这类 schema 库。需要把类型定义写两遍一份给 TypeScript 编译期一份给运行时。二是让编译器在生成 JavaScript 时自动把类型信息转成一份“元数据”带出去。这就是运行时类型元数据。第二种方式对开发者最友好因为类型定义只需要写一份。但难点在于元数据由谁生成、按什么格式生成、能不能覆盖泛型和嵌套类型、生成成本有多高。emitDecoratorMetadata就是早期探索的产物而 Rfclt 想解决的是如何在 TS 7.0 时代把这件事做得更完整、更干净。简单说运行时类型元数据要解决三个问题类型定义只写一份运行时不重复维护。编译后仍然能回答“这个字段是什么类型”这类问题。元数据不仅要能描述类还要能描述接口、类型别名、联合类型甚至泛型。只做到前两点很多方法是可行的第三点才是真正的分水岭。2. emitDecoratorMetadata 的机制与限制理解 Rfclt 之前必须先搞清楚旧方案为什么不够用。emitDecoratorMetadata是 TypeScript 编译器的一个选项。开启后编译器遇到装饰器时会额外生成三组元数据design:typedesign:paramtypesdesign:returntype例如下面的类import reflect-metadata; class UserService { getUser(id: number): User { // ... } }编译后大概会生成类似这样的代码__decorate([ __metadata(design:type, Function), __metadata(design:paramtypes, [Number]), __metadata(design:returntype, User) ], UserService.prototype, getUser, null);运行时通过Reflect.getMetadata(design:paramtypes, instance, getUser)就能拿到参数类型数组。这套机制解决了“有没有”的问题但离“好不好用”还有距离。核心限制如下限制说明必须使用装饰器没有装饰器的类不会生成元数据这意味着你要为了元数据引入装饰器语法依赖实验性特性experimentalDecorators和emitDecoratorMetadata长期处于实验状态TS 新版本随时可能调整行为需要 reflect-metadata 垫片运行环境没有原生Reflect.metadata时必须引入额外库增加包体积和兼容成本类型覆盖有限接口、类型别名不会生成元数据普通类字段如果装饰器没挂到属性上也可能拿不到信息泛型信息丢失ListUser拿到design:type后只剩Array内部泛型参数不可见union/交叉类型失真string | number在元数据里通常变成Object完全无法还原真实类型如果你写过一个依赖注入框架一定体会过design:paramtypes拿到Object时的困惑。不是编译器不努力而是emitDecoratorMetadata的设计目标只是服务于装饰器场景从来没打算成为通用类型反射方案。项目中常见的替代方案是引入 zod 这类 schema 库const UserSchema z.object({ id: z.number(), name: z.string(), }); type User z.infertypeof UserSchema;这也是“一份定义两端使用”但 schema 定义本身仍然是额外代码。Rfclt 的思路更激进直接让编译器把.ts里的类型结构提取成元数据开发者不需要手动维护 schema。3. TS 7.0 为什么能带来转机TypeScript 7.0 最受关注的点是编译器从 TypeScript 自举实现切换到原生实现编译速度会有数量级提升。速度提升之外编译器架构变化还带来了另一个潜在红利转换插件和代码生成管线更有可能被重新设计。过去要做自定义代码转换需要借用 TypeScript Compiler API构造Program注册自定义 transformer再走一遍 emit 流程。步骤繁琐编译速度也会受影响。TS 7.0 的原生化改造给了团队重新设计编译管线的机会运行时类型元数据的生成逻辑也就有了被纳入正式编译流程的可能。Rfclt 这个项目名出现在 TS 7.0 语境下本身就是一种信号它瞄准的是“编译器原生支持类型元数据”的窗口期。如果类型元数据成为编译产物的一部分而不是某个装饰器附加的副作用整个生态的受益面会非常大依赖注入框架不再需要emitDecoratorMetadata。接口入参校验可以自动生成。ORM 可以根据实体类型自动推导查询结果类型。低代码平台能直接从类型定义生成配置面板。要注意的是TS 7.0 正式版尚未发布具体转换 API 和配置项还会有变化。但从编译器演进方向看把类型信息作为一等公民导出已经不是“要不要做”的问题而是“用什么方式做”的问题。4. Rfclt 的核心设计思路Rfclt 的思路可以拆成四个关键点编译期提取、无装饰器、可序列化、原生语法支持。4.1 编译期提取与emitDecoratorMetadata依赖装饰器不同Rfclt 希望在类型检查或代码生成阶段主动扫描并提取类型定义。只要代码里出现了interface、type、class、enum定义编译器就有机会把这些类型结构转换成元数据。这意味着你不必为了获得类型元数据而刻意写装饰器普通接口也能被识别。4.2 无装饰器装饰器的问题在于它改变了代码语义。你要在类上挂Entity()、在字段上挂Column()这些装饰器既是元数据来源也是运行时代码。如果类型提取完全发生在编译期装饰器就变得不再必要。代码里保留纯粹的 TypeScript 类型定义即可。这对那些不喜欢装饰器语法的团队尤其友好也从根上消除了experimentalDecorators带来的不确定性。4.3 可序列化运行时元数据不能是内存里的临时对象最好能导出成 JSON 或平台无关的中间格式。这样一份元数据既可以在 Node.js 服务端使用也可以传到前端甚至可以给其他语言的数据校验、接口文档工具消费。从工程角度看可序列化意味着“一次生成多处使用”这也让缓存和增量编译成为可能。4.4 原生语法支持设计上Rfclt 更倾向于支持 TypeScript 的完整类型语法包括基础类型string、number、boolean、null、undefined复合类型数组、元组、对象字面量泛型ListUser、PromiseResultT联合类型string | number交叉类型A B工具类型PartialT、PickT, id | name当然Omit、Partial这类工具类型最终要靠编译器展开成具体结构而不是保留一个名字。这也引出了实现层面的复杂度不是所有类型都能自动展开某些场景需要注解辅助。这里真正容易踩坑的地方是类型元数据不等于类型签名快照。你要的是“这个接口有哪些字段、字段是什么类型”而不是“这里写了一段类型文字”。所以从 AST 提取到最终元数据中间必须有类型检查器的参与才能把别名、泛型参数解析成实质结构。5. 最小实现做一个 Rfclt 风格的元数据生成器理解原理最好的方式是手写一个简化版。下面用 TypeScript Compiler API 做一个演示说明“不依赖装饰器也能从普通接口生成运行时类型元数据”。这段代码只是为了验证思路接口名会随 TS 版本变化实际使用 Rfclt 时请以项目文档为准。5.1 环境准备先初始化项目并安装依赖mkdir ts-runtime-meta-demo cd ts-runtime-meta-demo npm init -y npm install typescript npm install -D ts-node为了调试方便可以在 VSCode 里通过ts-node直接运行 TypeScript 脚本。如果你还不清楚怎么在 VSCode 里运行 TS 文件最简单的方式是装好 ts-node 后在终端执行npx ts-node src/collect-metadata.ts也可以配置 VSCode 的 “运行” 任务来调用这条命令。核心思路是让 TypeScript 文件先经过 ts-node 转译再交给 Node.js 执行。5.2 写一个类型元数据收集器我们以普通的interface和type为输入用 TypeScript 编译器解析源码再通过类型检查器获取字段类型。// src/collect-metadata.ts import * as ts from typescript; import * as path from path; const filePath path.resolve(__dirname, ../src/user.ts); const program ts.createProgram([filePath], { target: ts.ScriptTarget.ES2020, module: ts.ModuleKind.CommonJS, }); const checker program.getTypeChecker(); const sourceFile program.getSourceFile(filePath); interface FieldMeta { name: string; type: string; optional: boolean; } interface TypeMeta { kind: string; fields: FieldMeta[]; } const metadata: Recordstring, TypeMeta {}; function visit(node: ts.Node) { // 提取 interface 和 type 别名按名称收集字段 if (ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) { const name node.name.text; const type checker.getTypeAtLocation(node); const fields checker .getPropertiesOfType(type) .map((prop) { const propType checker.getTypeOfSymbolAtLocation(prop, node); return { name: prop.name, type: checker.typeToString(propType, node, ts.TypeFormatFlags.NoTruncation), optional: !!(prop.flags ts.SymbolFlags.Optional), }; }); metadata[name] { kind: node.kind ts.SyntaxKind.InterfaceDeclaration ? interface : type, fields }; } ts.forEachChild(node, visit); } visit(sourceFile); console.log(JSON.stringify(metadata, null, 2));这段代码的逻辑分成三步创建Program让 TypeScript 对整个项目做类型检查。遍历 AST找到 interface 和 type 声明。用checker把类型符号解析成字段列表并转成字符串类型名。注意这里没有添加任何装饰器也没有开启emitDecoratorMetadata。5.3 定义测试接口准备一个包含泛型和嵌套类型的用户模型// src/user.ts export interface User { id: string; name: string; age: number; tags: string[]; address?: { city: string; zip: string; }; } export type LoginRequest { username: string; password: string; }; export interface ApiResponseT { code: number; data: T; }5.4 运行并查看输出执行npx ts-node src/collect-metadata.ts预期输出类似{ User: { kind: interface, fields: [ { name: id, type: string, optional: false }, { name: name, type: string, optional: false }, { name: age, type: number, optional: false }, { name: tags, type: string[], optional: false }, { name: address, type: { city: string; zip: string; }, optional: true } ] }, LoginRequest: { kind: type, fields: [ { name: username, type: string, optional: false }, { name: password, type: string, optional: false } ] }, ApiResponse: { kind: interface, fields: [ { name: code, type: number, optional: false }, { name: data, type: T, optional: false } ] } }看到这个输出就能直观理解 Rfclt 的目标把interface User这样一个在传统编译中会完全消失的类型变成运行时可读的结构化数据。它不需要装饰器不需要emitDecoratorMetadata只需要编译器在编译时做一次类型结构提取。如果你发现输出里缺少类型第一件事不是检查生成代码而是检查tsconfig.json里target和module配置是否正确。类型提取依赖完整的类型检查过程配置错误会导致源文件被跳过或类型解析失败。5.5 在运行时消费元数据拿到元数据之后可以把它保存成 JSON 文件供运行时使用。我们可以写一个简单的类型校验函数模拟真实场景中的参数校验。// src/validate.ts import * as fs from fs; const metadata JSON.parse( fs.readFileSync(require.resolve(../dist/metadata.json), utf-8) ); const typeGuards: Recordstring, (v: unknown) boolean { string: (v): v is string typeof v string, number: (v): v is number typeof v number, boolean: (v): v is boolean typeof v boolean, }; function validate(value: unknown, typeName: string): string[] { const def metadata[typeName]; if (!def) return [Unknown type: ${typeName}]; if (typeof value ! object || value null) { return [Expect ${typeName} to be an object]; } const errors: string[] []; for (const field of def.fields) { const fieldValue (value as Recordstring, unknown)[field.name]; if (fieldValue undefined) { if (!field.optional) errors.push(Missing field: ${field.name}); continue; } if (!typeGuards[field.type]?.(fieldValue)) { errors.push(Field ${field.name} should be ${field.type}); } } return errors; } export { validate };这里做了一个很粗糙的校验但它证明了关键点运行时会话过程中我们能拿到一个叫metadata.json的文件作为“类型事实表”而不是依赖编译器注入的装饰器数据。在实际工程里类型提取和运行时校验之间通常还会隔一层生成器先把所有类型导出成 JSON前端和后端共享同一份元数据。这也意味着接口变了元数据会跟着变校验规则同步更新不再需要人肉维护两套定义。6. 运行结果与效果验证整个 demo 项目可以分成三个验证步骤第一步验证元数据生成是否完整npx ts-node src/collect-metadata.ts dist/metadata.json cat dist/metadata.json输出文件里应该能看到User、LoginRequest、ApiResponse三个类型定义。第二步验证运行时校验是否生效// src/run-demo.ts import { validate } from ./validate; const validUser { id: 1, name: Alice, age: 18, tags: [a] }; const invalidUser { id: 1, name: Alice, age: 18, tags: [] }; console.log(validate(validUser, User)); // 期望输出: [] console.log(validate(invalidUser, User)); // 期望输出: [Field id should be string, Field age should be number]第三步确认编译产物里没有装饰器相关代码。你可以打开生成的.js文件搜索__decorate或__metadata如果搜索结果为空就说明这套方案完全不依赖emitDecoratorMetadata。如果运行失败优先检查三个方面src/user.ts的 export 是否写对程序能否正确解析到该文件。metadata.json是否生成校验函数是否能读到文件。运行时字段类型是否与编译器输出的类型字符串一致。7. 常见问题与排查思路问题现象可能原因排查方式解决方案生成的元数据为空sourceFile 路径错误或 tsconfig 未正确加载检查 Program 是否真的包含了目标文件使用绝对路径并确认rootDir配置泛型类型只显示T类型检查器没有在泛型实例化点展开先给具体类型做一次typeToString调用观察是否展开需要在生成阶段对泛型做实例化展开而不是只取类型参数名string | number变成string类型格式化配置把联合类型截断手动打印checker.typeToString的完整结果调整TypeFormatFlags或换用结构化的类型表示VSCode 调试时 ts-node 报错Node 版本或 ts-node 版本不兼容查看错误堆栈是否涉及 ts-node 降级升级 ts-node 或改用 tsx 运行类型别名包含PickT, K却无法解析工具类型还没被编译器展开检查该类型别名是否依赖外部导入先解析导入关系再处理工具类型展开8. 工程落地与最佳实践如果你准备在自己的项目里引入类似 Rfclt 的思路这些建议可以先收藏。第一把元数据生成当成构建步骤的一部分不要放在应用启动时动态计算。动态提取类型会拖慢启动速度而且不利于缓存。更合理的做法是编译时生成metadata.json运行时直接读取静态文件。第二元数据只描述类型结构不保存真实业务数据。注意不要往类型信息里塞敏感信息避免意外的数据泄露。第三不要用元数据替代所有安全校验。运行时校验只是第一道防线对于涉及权限、金额、状态机的字段仍然需要业务代码做精细化校验。类型校验只能保证“形状正确”不能保证“业务正确”。第四考虑与 zod、valibot 等 schema 库共存。如果你已经用 zod 做了复杂业务校验大可以让元数据承担基础结构校验zod 承担复杂规则校验各管一段而不是全面替换。第五注意版本兼容。TS 7.0 还在演进中自定义 transformer 的 API 很可能变化。生产项目接入时建议锁定 TypeScript 版本并在 CI 里加入类型元数据快照测试。生成结果一旦发生非预期变化CI 应该立刻报错。第六对于大型项目建议对元数据做增量生成。比如只收集变更文件对应的类型再合并进整体元数据文件。这样既保存编译速度又避免全量生成的性能损耗。第七让元数据和接口文档工具打通。既然已经有了结构化类型信息Swagger、OpenAPI、Mock 数据生成器都可以复用这份数据。一鱼多吃是这套方案最有吸引力的地方。9. 总结Rfclt 带来的真正价值回头看Rfclt 这类运行时类型元数据方案最大价值不在于“多了一个 npm 包可以用”而在于它把 TypeScript 类型从编译期的“一次性符号”变成了可持续的结构化资产。过去我们要手动维护 schema、写 DTO、重复校验逻辑如果编译器能原生输出类型元数据很多工程环节都能自动化。对普通前端工程师来说可能最直接的收益是后端接口返回结构变了前端能够用和 TypeScript 同一份类型来源自动生成校验规则不再出现“代码里类型是对的线上接口字段是缺的”这种割裂。对框架作者来说依赖注入、参数校验、数据库映射都不再需要依赖emitDecoratorMetadata编译配置可以更干净。当然也要正视现实TS 7.0 尚未正式发布Rfclt 本身也处在早期阶段API 会变性能预期需要实测。但方向已经很清晰运行时类型元数据会从“装饰器副作用”转变成“编译器基础能力”。建议有精力的话现在就用最小编译器脚本跑通“类型到 JSON”的链路等 TS 7.0 正式发布后再切换到官方或社区方案就会顺畅很多。如果你正在做 API 校验、依赖注入框架或者维护一个跨端共享类型的大型项目可以多关注运行时类型元数据这条路线。它是 TypeScript 生态里少数能同时影响框架作者、工具链作者和业务开发者的方向。