TypeScript 7.0 正在把一批旧的编译选项从“警告”变成“不再工作”其中影响面最大的就是emitDecoratorMetadata。这个选项曾经是 NestJS、TypeORM、class-validator 等领域模型代码能拿到参数类型和属性类型的关键。Rfclt 提供了一条新的运行时类型元数据路径它不依赖emitDecoratorMetadata也不需要你在每个类上手工维护一套类型定义文件。在讨论 Rfclt 怎么落地之前先要搞清楚旧的元数据机制为什么被放弃以及运行时类型元数据在 TS 7.0 里到底缺了什么。如果你的项目还在使用reflect-metadata或者代码里频繁出现Reflect.getMetadata(design:paramtypes, ...)这篇文章会直接关系到你的升级决策。下面从 TS 7.0 的弃用背景开始讲清楚问题链路再用一个最小生成器示例说明 Rfclt 的落地方式最后给出迁移时的报错排查顺序和检查清单。1. 为什么 TS 7.0 之前emitDecoratorMetadata能工作之后不能1.1emitDecoratorMetadata解决了什么问题在旧版 TypeScript 装饰器规范下如果tsconfig.json同时开启了experimentalDecorators和emitDecoratorMetadata编译器遇到带装饰器的类、方法、属性或参数时会额外生成一组Reflect.metadata调用。这些调用会把三样东西注册进元数据design:type被装饰成员的类型。design:paramtypes构造函数或方法的参数类型列表。design:returntype方法返回值类型。典型代码如下Controller(/user) class UserController { constructor(private readonly userService: UserService) {} }在旧版本中编译器编译后大致会生成类似下面的逻辑__decorate([ Controller(/user), __metadata(design:paramtypes, [UserService]) ], UserController);框架拿到design:paramtypes之后就知道UserController的构造函数需要注入UserService。这正是很多依赖注入容器能自动推断构造函数参数的原因。问题是这个行为从来没有进入 ECMAScript 标准。它不是 JavaScript 语言的能力而是 TypeScript 编译器自定义的一段“发射逻辑”。标准装饰器提案中装饰器只暴露被装饰元素的结构并不会自动给出被装饰成员的类型信息。类型信息在编译后仍然会消失。1.2 TS 7.0 清理旧选项对运行时的真实影响TS 7.0 是编译器架构切换后的一个大版本。除了迁移到新的代码生成后端它还会清理一批历史遗留选项。你可以把emitDecoratorMetadata的弃用提示想象成和其他旧选项一样Option baseUrl is deprecated and will stop functioning in TypeScript 7.0.emitDecoratorMetadata虽然没有和baseUrl在同一时间点被宣布但方向和逻辑是一致的TypeScript 不想继续为不是标准的元数据发射机制维护一套分支复杂的旧逻辑尤其是新装饰器规范已经来到标准轨道之后。真实影响在于运行时。关闭emitDecoratorMetadata后编译器不再生成design:*元数据。于是所有依赖这套元数据的库都会在运行时拿不到类型信息。常见表现有依赖注入框架无法推断构造函数参数。ORM 无法从实体属性反推列类型。校验库无法自动检查属性类型。序列化工具不知道字段是可选的还是必填的。这不是“某个库小版本出 bug”而是底层元数据源被切断。只要代码还在运行时依赖design:*就必须找到新的元数据来源。1.3 Rfclt 在元数据链路中的位置Rfclt 做的事情是把“从 TypeScript 类型信息生成运行时元数据”这一步从编译器的装饰器发射中拆出来放到构建期显式执行。这里的关键区别是旧机制写类 - 编译时隐式生成元数据 - 运行时在装饰器中反射获取。Rfclt 思路写类 - 构建期扫描类型 - 生成独立元数据文件 - 运行时直接读取该文件。Rfclt 不需要你在每个类上额外维护一份 schema因为它读取的是 TypeScript 编译器已经有的类型信息。它也不需要打开experimentalDecorators或emitDecoratorMetadata因为它不依赖旧装饰器执行顺序而是通过 TypeScript Compiler API 在构建阶段把类型结构提取出来。如果把运行时类型信息比作一份地图旧方案是在路上插牌子Rfclt 则是在出发前先画好地图运行时不猜类型直接查表。2. 运行时类型元数据到底缺了什么为什么不能靠反射补上2.1 类型信息在编译器输出中的消失过程先看一段简单的 TypeScript 代码class User { id: number; name: string; email?: string; constructor(id: number, name: string) { this.id id; this.name name; } }编译成 JavaScript 之后你已经看不到任何number、string的痕迹class User { constructor(id, name) { this.id id; this.name name; } }JavaScript 运行时只有值没有静态类型。如果 Rfclt 不提前把类型信息保存下来运行时无论如何反射都只能看到“这个属性叫id”永远看不到“id是number类型”。这也是很多人误以为“运行时反射可以替代类型元数据”的原因。反射能看到结构和值但看不到编译期才存在的类型标注。2.2 旧框架对 design:* 元数据的依赖很多框架在运行时并不会直接读取 TypeScript 类型它们读取的是Reflect.getMetadata里的内容。以几个常见场景为例框架或库依赖内容升级 TS 7.0 后的常见表现NestJSdesign:paramtypes推断依赖注入构造函数参数无法自动注入TypeORMdesign:type推断实体列类型实体字段类型缺失class-validatordesign:type做类型校验属性校验不生效class-transformerdesign:type做反序列化类型转换嵌套对象无法转换routing-controllersdesign:paramtypes做参数绑定请求参数无法自动映射这些库不是都不能用了而是必须改成显式传参方式例如 NestJS 的Inject()或者 TypeORM 的Column()显式类型。但这么做会让代码冗余并且失去“类型信息自动传递”的便利。Rfclt 想补的正是这种被 TS 7.0 抽走的自动传递能力。2.3 运行时类型元数据需要覆盖的三个维度一个相对完整的运行时类型元数据方案至少要覆盖三个维度维度说明运行时用途属性类型每个字段是什么类型、是否可选校验、序列化、表单生成构造参数类型构造函数参数列表依赖注入、参数解析方法的入参与出参类型方法参数和返回值API 契约、搜索文档、RPC 参数校验在最小实现里可以优先覆盖属性类型和构造参数类型。返回值类型往往和业务校验关系不大但如果是做 RPC 或 OpenAPI 文档生成最好也一并生成。Rfclt 的价值不是发明一套新类型系统而是把 TypeScript 已有的类型模型在编译期拷贝一份到运行时可读的数据结构中。3. 从构建期拿到类型信息Rfclt 的生成式实现3.1 整体流程Rfclt 的一个可落地实现路径是生成一个.meta.ts文件文件内容包含每个类的属性结构。整体流程如下配置一个构建脚本输入需要扫描的源码文件列表。创建 TypeScript Program走编译器类型检查通道。遍历 SourceFile 中的类声明和属性声明。从 TypeChecker 获取每个属性的静态类型。把结果写成独立模块例如src/generated/rfclt.meta.ts。运行时直接 import 这个模块不再依赖Reflect.getMetadata。这个流程的好处是生成结果可以进入版本控制。团队成员不需要执行额外脚本就能通过import使用同一份元数据。3.2 遍历 AST 生成类属性元数据下面用一个最小脚本演示核心逻辑。运行环境需要安装 TypeScript以及一个能直接执行 TS 脚本的工具例如tsx或ts-node。import * as ts from typescript; import * as fs from node:fs; import * as path from node:path; interface PropertyMeta { type: string; optional: boolean; } interface ClassMeta { properties: Recordstring, PropertyMeta; } function collectClassMetadata(fileNames: string[], options: ts.CompilerOptions) { const program ts.createProgram(fileNames, options); const checker program.getTypeChecker(); const classes: Recordstring, ClassMeta {}; for (const sourceFile of program.getSourceFiles()) { if (sourceFile.isDeclarationFile) { continue; } ts.forEachChild(sourceFile, (node) { if (!ts.isClassDeclaration(node) || !node.name) { return; } const className node.name.text; const properties: Recordstring, PropertyMeta {}; for (const member of node.members) { if (!ts.isPropertyDeclaration(member) || !member.name) { continue; } const propertyName member.name.getText(sourceFile); const propertyType checker.getTypeAtLocation(member); const typeText checker.typeToString(propertyType, node, ts.TypeFormatFlags.NoTruncation); properties[propertyName] { type: typeText, optional: member.questionToken ! undefined }; } classes[className] { properties }; }); } return classes; } const projectRoot path.resolve(__dirname, ..); const fileNames [path.join(projectRoot, src/entities/user.ts)]; const options: ts.CompilerOptions { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.NodeNext, strict: true }; const metadata collectClassMetadata(fileNames, options); const output export const metadata ${JSON.stringify({ classes: metadata }, null, 2)} as const;\n; fs.writeFileSync(path.join(projectRoot, src/generated/rfclt.meta.ts), output);这段代码的核心是checker.getTypeAtLocation(member)。它拿到的是编译器解析后的真实类型而不是源代码字符串。对于id: number输出就是number对于email?: string输出会记录optional: true。这里要注意示例为了控制篇幅只处理了属性声明。实际项目中通常还要处理继承关系、泛型参数、构造函数的parameterProperties比如constructor(private id: number)这种写法就不会出现在member.name的普通属性遍历中。3.3 生成独立的.meta.ts文件假设源码是这样的// src/entities/user.ts export class User { id: number; name: string; email?: string; }脚本生成的结果大致如下export const metadata { classes: { User: { properties: { id: { type: number, optional: false }, name: { type: string, optional: false }, email: { type: string, optional: true } } } } } as const;生成文件可以放在src/generated目录中并提交到 git。运行时和业务代码都不需要再触发 TypeScript 编译器的类型检查直接import这个模块就能拿到结构化信息。3.4 在 tsconfig 中关闭旧的 decorator 开关Rfclt 生成器不需要emitDecoratorMetadata也不需要experimentalDecorators。如果项目还没有迁移到新装饰器规范建议按下面方向调整tsconfig.json{ compilerOptions: { target: ES2022, module: NodeNext, strict: true, experimentalDecorators: false, emitDecoratorMetadata: false } }如果你的业务代码还在使用旧装饰器语法且框架又要求experimentalDecorators那么迁移要分两步先把依赖design:*的框架逻辑改造为显式传参或 Rfclt 元数据校验再把装饰器语法切到标准装饰器。不要在同一个版本里同时切换编译器底层和框架依赖否则问题会混在一起难以定位。4. 在运行时消费这些元数据4.1 用类装饰器接入校验有了生成好的元数据文件运行时消费方式就很简单。下面用一个类装饰器实现“必填字段和基础类型校验”。import { metadata } from ./generated/rfclt.meta.js; function getClassMeta(ctor: Function) { const className ctor.name; return metadata.classes[className as keyof typeof metadata.classes]; } export function ValidateRfclt() { return function T extends new (...args: any[]) any( Ctor: T, _context: ClassDecoratorContext ) { return class extends Ctor { constructor(...args: any[]) { super(...args); const classMeta getClassMeta(Ctor); if (!classMeta) { return; } for (const [key, schema] of Object.entries(classMeta.properties)) { const value (this as any)[key]; if (!schema.optional value undefined) { throw new TypeError(Property ${key} is required); } if (value ! undefined typeof value ! schema.type) { throw new TypeError(Property ${key} should be ${schema.type}); } } } }; }; }使用方式import { ValidateRfclt } from ./decorators/validate-rfclt; ValidateRfclt() class UserDTO { id!: number; name!: string; email?: string; } const user new UserDTO(); user.id 1; user.name Alice;如果id或name没有赋值装饰器会在构造函数中抛出异常。这种实现虽然简单但已经能演示 Rfclt 的核心价值类型信息在运行时是只读数据而不是隐藏在编译器内部逻辑里。注意示例只做基础typeof校验不支持嵌套对象和数组类型。生产环境中需要递归解析schema.type或者把类型信息拆成更细的节点例如{ kind: array, itemType: string }。4.2 调试验证用测试断言元数据正确性在 Rfclt 落地过程中最容易踩的坑是“元数据生成了但是不对”。建议给生成的.meta.ts写一组单元测试import { describe, expect, it } from vitest; import { metadata } from ../generated/rfclt.meta.js; import { User } from ../entities/user.js; describe(Rfclt runtime metadata, () { it(should describe User 的属性类型, () { const props metadata.classes.User.properties; expect(props.id.type).toBe(number); expect(props.id.optional).toBe(false); expect(props.email.optional).toBe(true); }); it(should keep class name stable, () { expect(metadata.classes.User).toBeDefined(); expect(User.name).toBe(User); }); });如果将来有人改了实体类型但忘记重新生成元数据测试就会失败。这也是推荐把生成文件提交到版本控制的原因测试能第一时间发现元数据和源码不一致。4.3 运行环境差异Node、浏览器、打包器Rfclt 生成的.meta.ts最终会被编译成普通 JavaScript 模块。它不包含design:*也不依赖reflect-metadata因此在 Node.js、浏览器和打包器环境中都能正常运行。需要注意的差异如下环境需要处理的点Node.js ESM生成文件使用export const直接 import 即可浏览器原生 ESM避免在生成模块中引用 Node.js APIWebpack / Vite / esbuild生成模块没有装饰器副作用压缩器不会误删老版本 Node需要保证target和运行时兼容例如转译到 ES2019生产环境还有一个容易被忽略的点压缩器可能重命名类名但不会重命名字符串 key。如果元数据文件里的类名和运行时类名不一致查找就会失败。解决方式是生成时不要只保存类名字符串必要时保存构造函数引用或者用Symbol作为 key。5. 不用 Rfclt 的替代方案以及它们差在哪里5.1 手工 schema 与代码生成对比很多团队在 TS 7.0 来临后选择手写 zod schemaimport { z } from zod; export const UserSchema z.object({ id: z.number(), name: z.string(), email: z.string().optional() }); export type User z.infertypeof UserSchema;这种方式没有历史包袱但会引入额外的心智负担。实体类、数据库模型、接口 DTO 都需要单独维护一份 schema类型一变schema 容易漏改。Rfclt 走的是生成式路线类型信息来源仍然是 TypeScript 类型检查器理论上更容易和现有实体类保持一致。5.2 标准装饰器元数据 Symbol.metadata 的补充位置新的 ECMAScript 装饰器提案中提供了Symbol.metadata作为装饰器元数据的标准入口。它的定位是 ECMAScript 标准层面的元数据容器但它不会自动填充 TypeScript 类型信息。也就是说Symbol.metadata能告诉你“这个类被哪些装饰器访问过”但不能告诉你“这个属性是 number 还是 string”。Rfclt 可以把生成的类型信息挂到Symbol.metadata上从而兼容标准装饰器体系。具体做法是在生成代码中保留类型描述对象在运行时把该对象注册到类的Symbol.metadata上。这样既不会依赖旧的design:*也能让框架通过标准入口读取。5.3 方案选型速查表方案是否生成代码对 TS 7.0 兼容性运行时开销维护成本适用场景手写 zod / io-ts不生成兼容中较高接口边界明确、全新项目继续依赖emitDecoratorMetadata不生成不兼容中不适用于 7.0不推荐继续使用transformer 类工具编译期生成需要构建器支持小中对构建链路有控制权Rfclt 生成式元数据构建期生成.meta.ts兼容小低存量实体想要自动迁移选型时不要只看“能不能校验类型”。要问三个问题运行时读元数据的方式是否标准生成结果是否可版本控制类型变更时是否会产生提示。Rfclt 的生成式思路在这三方面相对均衡。6. 从旧版本迁移到 TS 7.0 的排查路径和最佳实践6.1 典型报错与定位方法迁移到 TS 7.0 后旧项目通常会先出现运行时错误而不是编译错误。因为关闭emitDecoratorMetadata后类型仍能通过编译但运行时元数据缺失。下面按现象排查现象直接原因排查顺序启动时报缺少参数元数据框架通过design:paramtypes做依赖分析先搜索design:paramtypes和Reflect.getMetadata控制器注入参数变成 undefined依赖注入容器无法推断构造参数类型检查框架是否支持Inject等显式 Provider校验库不再校验类型class-validator 依赖design:type切换到基于 Rfclt 的 schema 校验序列化后字段丢失类型转换class-transformer 依赖design:type改用生成元数据或显式类型声明元数据文件 import 失败moduleResolution或 import 后缀问题确认生成文件路径和NodeNext模块解析规则排查顺序首先看输入是否正确也就是生成脚本是否真的覆盖了对应文件再看tsconfig是否关闭了emitDecoratorMetadata然后看运行时 import 的是不是最新生成的元数据最后才怀疑框架兼容性。不要一上来就改框架配置。6.2 三个最容易被忽略的坑第一个坑把类名当作唯一元数据 key。压缩器、改名、代码拆分都可能让Ctor.name变化。生成文件保存的是字符串类名运行时却通过Ctor.name查找一旦不一致就拿到空元数据。推荐做法是在生成时输出一个辅助函数直接保存类引用import { User } from ../entities/user.js; export const classMetaMap new MapFunction, ClassMeta([ [User, { properties: { /* ... */ } }] ]);第二个坑继承属性没被收集。如果Admin extends User生成器只遍历了Admin自己的members那么Admin实例上的id、name在运行时没有元数据。解决方案是生成时递归收集父类属性或者运行时沿着原型链层层查找。第三个坑optional和undefined混淆。email?: string和email: string | undefined在类型语义上不同。前者表示可以缺失后者表示值可以是undefined。校验逻辑必须区分处理不能只用typeof value undefined判断。建议在元数据里额外保存includesUndefined标志。6.3 发布前检查清单迁移不是把emitDecoratorMetadata改成false就算完成。下面是一份可复用的检查清单检查项验证方式所有emitDecoratorMetadata引用已清理执行grep -r emitDecoratorMetadata --include*.json --include*.ts .代码中不再依赖Reflect.getMetadata(design:搜索design:type、design:paramtypesRfclt 生成脚本进入构建流程npm run build后检查src/generated/rfclt.meta.ts是否有更新生成文件已提交版本控制git status 中能观察到元数据变更单元测试覆盖关键实体元数据运行测试套件断言属性类型和 optional 标记生产打包产物包含元数据在压缩产物中搜索类名字符串或Symbol.metadata依赖注入框架改用显式 Provider逐个验证入口控制器启动正常校验逻辑覆盖嵌套类型对type: Array或对象类型做递归校验测试发布前最应该重视的是“生成脚本是否可复现”。如果元数据只在本地生成CI 重新拉代码后不执行生成步骤就会出现本地正常、线上缺失的情况。推荐把元数据生成命令纳入npm run build或 CI pipeline 的第一步。TypeScript 7.0 对旧装饰器元数据的清理本质上是在提醒开发团队运行时需要什么信息应该显式声明或构建期生成而不是依赖编译器的隐式魔法。Rfclt 这类方案的价值不在于生成多少行元数据代码而在于它把运行时类型信息变成一份可检查、可测试、可版本控制的产物。如果你正在维护一个老项目先不要一次性迁移所有实体。建议先挑一个没有复杂继承、也没有泛型的 DTO 类接入 Rfclt跑通“源码 - 生成元数据 - 运行时校验 - 单测断言”这条链路。再逐步扩展到控制器参数、ORM 实体和 API 文档生成。泛型和类继承这类复杂场景放到第二阶段等生成器稳定后再处理。