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 等属性。

典型使用场景：日志、权限校验、防抖、缓存包装。

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

真正棘手的地方不在语法，而在于把“声明式写法”误当作“运行时逻辑”。它只是让配置更集中，但所有副作用仍需你手动处理好时序和作用域。