JavaScript Decorator 是处于 Stage 3 提案阶段的语法糖，需 Babel 或 TypeScript 转译，本质是修饰类、方法等的函数，接收固定参数并返回修改后的描述符或构造函数，执行于类定义阶段而非运行时。
JavaScript Decorator 不是标准语法，目前仍处于 Stage 3 提案阶段，所有使用都依赖 Babel、TypeScript 等转译工具；直接在浏览器或 Node.js 原生环境中运行会报 SyntaxError: Unexpected token '@'。
Decorator 是什么：语法糖，不是运行时特性
Decorator 本质是函数，用于修饰类、类属性（字段）、方法、访问器（get/set）或参数。它本身不改变 JavaScript 的执行模型，只是提供一种更简洁的声明式写法，底层靠转译器展开为普通函数调用。
常见错误现象：
- 写了
@log却没配 Babel 插件（如@babel/plugin-proposal-decorators），直接报错 - 在 TypeScript 中启用了
experimentalDecorators: true，但忘了开emitDecoratorMetadata: true（影响反射元数据） - 误以为 Decorator 能修改私有字段（
#field），实际目前提案不支持装饰私有成员
如何装饰类方法：接收三个参数
方法 Decorator 函数签名固定为：(target, propertyKey, descriptor)。其中 descriptor 是 Object.getOwnPropertyDescriptor(target, propertyKey) 返回的对象，可修改其 value、enumerable、writable 等属性。
立即学习“Java免费学习笔记（深入）”；
典型使用场景：日志、权限校验、防抖、缓存包装。
function log(target, propertyKey, descriptor) {
const originalMethod = descriptor.value;
descriptor.value = function(...args) {
console.log(`Calling ${String(propertyKey)} with`, args);
return originalMethod.apply(this, args);
};
return descriptor;
}
class Calculator {
@log
add(a, b) {
return a + b;
}
}
注意点：
-
descriptor.value是原始方法，必须用apply或call绑定this，否则丢失上下文 - 若方法是异步的（
async），originalMethod返回的是 Promise，装饰器需显式await或返回新 Promise - Babel 默认使用
legacy: true模式，此时descriptor可能为undefined（对字段装饰），应改用legacy: false+decoratorsBeforeExport: true
装饰类本身：用于注册、配置或元数据注入
类 Decorator 接收一个参数：constructor（即类本身），必须返回一个构造函数（可为原类，也可替换为子类或代理）。
常见用途：
- 自动向 DI 容器注册（如 NestJS 的
@Injectable()） - 添加静态属性（如
constructor.route = '/users'） - 冻结实例（
Object.freeze(constructor.prototype)）
function apiRoute(path) {
return function(target) {
target.route = path;
// 可选：为原型方法统一加请求拦截
const proto = target.prototype;
for (const key of Object.getOwnPropertyNames(proto)) {
if (key !== 'constructor' && typeof proto[key] === 'function') {
const original = proto[key];
proto[key] = function(...args) {
console.log(`[API] ${path}${key}:`, args);
return original.apply(this, args);
};
}
}
};
}
@apiRoute('/api/v1')
class UserService {
fetch() { return 'data'; }
}
关键限制：
- 不能在类 Decorator 中访问实例字段（
this.field），因为此时实例尚未创建 - 若返回新构造函数，需确保继承原
prototype，否则方法丢失 - TypeScript 中若未启用
emitDecoratorMetadata，Reflect.getMetadata将始终返回undefined
为什么容易出问题：执行时机与 this 绑定最常被忽略
Decorator 在**类定义阶段**执行（模块加载时），而非实例化或调用时。这意味着：
- 所有装饰器函数在
new MyClass()之前就已运行完毕 - 方法装饰器中的
target是类的prototype，不是实例，所以target.xxx读不到实例属性 - 箭头函数在装饰器内无法正确捕获实例
this，必须用function+apply/call - 如果装饰器内部依赖异步初始化（如从 config service 读取配置），会失败——因为装饰阶段不允许 await
真正棘手的地方不在语法，而在于把“声明式写法”误当作“运行时逻辑”。它只是让配置更集中，但所有副作用仍需你手动处理好时序和作用域。
