结论先行:TypeScript 里同时存在两套互不兼容的装饰器——开了 experimentalDecorators 走 2015 年前后的旧实验实现,不开则从 TS 5.0 起走 TC39 标准装饰器。两者签名不同、求值时机不同,标准版暂不支持参数装饰器,也没有旧版 emitDecoratorMetadata 那样的类型元数据发射。NestJS、TypeORM 等依赖注入/ORM 框架的命脉恰恰是旧版的 design:paramtypes 元数据,所以它们至今留在旧标准上。写业务代码前先确认项目用的是哪一套,混用是大量「装饰器不生效」问题的根源。
一、历史包袱:为什么会有两套
装饰器提案 2014 年前后进入 TC39,TypeScript 早在 1.x 时代就按早期草案实现了实验版本,并用 experimentalDecorators 标志隔离。Angular 2、NestJS、TypeORM、MobX 等一大批框架在这个实现上建立了生态。但提案此后多次推倒重来,2022 年前后定稿的新方案与旧实现语义差异太大,无法原地升级。TS 5.0(2023 年 3 月)选择两条腿走路:保留旧实现不动,另起炉灶实现标准版,由编译标志决定走哪条路。这也是「同一个 @ 符号,两种语言」的由来。
二、两套写法对照
旧版装饰器接收 (target, propertyKey, descriptor),配合 reflect-metadata 还能拿到反射类型:
// tsconfig: experimentalDecorators: true, emitDecoratorMetadata: true
function Log(target: any, key: string, desc: PropertyDescriptor) {
const orig = desc.value;
desc.value = function (...args: unknown[]) {
console.log('call', key);
return orig.apply(this, args);
};
}
class Service {
@Log
run() {}
}标准版装饰器接收 (value, context),context 携带 kind、name、static、private 以及 addInitializer 等能力:
// tsconfig: 不开 experimentalDecorators(TS 5.0+)
function Log<This, Args extends unknown[], Return>(
value: (this: This, ...args: Args) => Return,
context: ClassMethodDecoratorContext
) {
return function (this: This, ...args: Args) {
console.log('call', String(context.name));
return value.apply(this, args);
};
}标准版可以直接替换方法、访问器与类本身,还能通过 context.access 暴露读写钩子,表达能力其实更强;但它刻意不做「魔法」,一切修改都显式发生在返回值里。
三、关键差异清单
| 维度 | 旧实验版 | TC39 标准版(TS 5.0+) |
|---|---|---|
| 启用方式 | experimentalDecorators: true | 默认(不开旧标志) |
| 方法装饰器签名 | (target, key, descriptor) | (value, context) |
| 参数装饰器 | 支持 | 不支持 |
| 类型元数据 | emitDecoratorMetadata 发射 design:paramtypes 等 | 无对应机制(元数据提案另行推进,以官方为准) |
| 求值与执行 | 装饰器表达式求值后自底向上应用 | 求值顺序与应用顺序分离,语义更严格 |
| 依赖库 | 常配 reflect-metadata | 不需要 reflect-metadata |
| 代表生态 | NestJS、TypeORM、Angular 工具链 | 新兴库、标准优先的项目 |
最致命的一条是元数据:旧版配合 emitDecoratorMetadata,编译器会把构造函数参数的类型信息写进 design:paramtypes,DI 容器据此知道该注入什么。标准版没有这个发射机制,参数装饰器也不存在——这两点直接判了「NestJS 无痛切换」的死刑。
四、NestJS/Angular 为什么还在旧版
NestJS 的依赖注入完全建立在构造函数参数类型元数据上:constructor(private users: UsersService) 能被自动注入,靠的就是 emitDecoratorMetadata 发射的 design:paramtypes,运行期由 reflect-metadata 读取。切到标准装饰器等于抽掉 DI 的地基,除非框架重写注入机制或等待装饰器元数据提案落地并普及。TypeORM 的实体列定义、class-validator 的校验规则同样依赖旧版语义与反射元数据。
Angular 的情况略有不同:@Component/@Injectable 的元数据主要由 Angular 自己的编译器(ngtsc)静态分析处理,不完全依赖运行期反射,但其装饰器写法与工具链仍沿用旧标准语义,生态迁移同样需要时间。结论是:这些框架的 tsconfig 里 experimentalDecorators 与 emitDecoratorMetadata 短期内不会消失,跟着框架的脚手架配置走即可,不要手动「升级」成新标准。
五、实践建议
- 用 NestJS/Angular/TypeORM:保持脚手架默认配置,引入 reflect-metadata(通常在入口第一行),不要混入标准版装饰器写法。
- 写通用库:优先标准版,签名里的 context 类型更完备,面向未来;需要兼容旧项目时提供双入口或明确 peer 约束。
- 排查「装饰器不生效」:先查 tsconfig 是否开了 experimentalDecorators、是否漏了 reflect-metadata、构建工具(esbuild/SWC/Babel)的装饰器模式是否与 tsc 一致——三套编译器各有一个装饰器开关,不一致是高频事故点。
- 关注元数据提案进展,但在框架官方宣布迁移前不要自行切换(以官方文档为准)。
六、绕开装饰器之争的另一条路
装饰器标准的拉扯,本质是「后端框架复杂度」的一个缩影:DI、ORM、校验、元数据,每一层都要团队自己维护。如果项目是商城、会员、内容类应用,其实可以跳过自建 NestJS 后端这一整层——用「api工厂」这类开放 SaaS 平台,用户、商品订单、微信支付/支付宝、优惠券、CMS、短信验证码、文件存储都是现成能力,自带管理后台,前后台接口全开放。前端按端选 SDK:微信小程序 apifm-wxapi、Vue/Web apifm-webapi、抖音 apifm-ttapi、uni-app 与 Flutter 各有对应包,统一返回 {code,data,msg},不需要任何装饰器知识。
免费会员 0 元/年(非商业),专业版 399 元/年、增值版 988 元/年,价格与能力见 https://www.it120.cc/price.html ;接口先在 https://www.it120.cc/playground.html 调通再集成。把工程精力留给真正差异化的业务,而不是框架标准的迁移成本。
文章标签
相关产品
api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。