TypeScript 装饰器问题：装饰器语法与配置

TypeScript 引入装饰器（Decorators）是为了实现对类、方法、属性等元素的修改或注解。然而，由于 TypeScript 经历了从“实验性旧版装饰器”向“ECMAScript 标准装饰器”的演进，开发者在配置文件和语法选择上极易产生混淆。错误的配置会导致编译报错，使得功能无法正常使用。

第一步：理解两种装饰器模式

TypeScript 目前存在两套装饰器体系，它们互不兼容，必须在 tsconfig.json 中明确指定其中一种。

1. 旧版装饰器（Legacy Decorators）：这是 TypeScript 早期的实现方式，目前广泛应用于 Angular（旧版本）、NestJS 和 TypeORM 等成熟框架中。它通过设置 experimentalDecorators 为 true 来启用。
2. 新版装饰器（Standard Decorators）：这是基于 ECMAScript 提案的标准实现，自 TypeScript 5.0 起作为正式功能推出。它支持更丰富的功能（如自动访问器装饰器），需要将 experimentalDecorators 设置为 false，并通常启用 compilerOptions.emitDecoratorMetadata 以配合类型元数据的使用。

第二步：配置 tsconfig.json

打开项目根目录下的 tsconfig.json 文件，找到 compilerOptions 节点。根据项目需求，选择以下两种配置方案之一进行修改。

方案 A：启用旧版装饰器（适用于遗留项目）

如果项目依赖旧版框架或尚未迁移到 TypeScript 5.0+，请使用此配置。

1. 定位 compilerOptions 对象。
2. 添加或修改以下配置项：

{
  "compilerOptions": {
    "target": "ES6",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

• experimentalDecorators: true：告诉编译器启用旧版装饰器语法。
• emitDecoratorMetadata: true：启用类型元数据发射，允许反射库获取参数类型。

方案 B：启用新版装饰器（适用于新项目）

如果使用 TypeScript 5.0 或更高版本开发新项目，建议使用此配置。

1. 定位 compilerOptions 对象。
2. 添加或修改以下配置项：

{
  "compilerOptions": {
    "target": "ES2022",
    "experimentalDecorators": false
  }
}

• experimentalDecorators: false：关闭旧版实验性功能，从而激活新版标准装饰器支持。
• 注意：新版装饰器要求 target 至少为 ES2022，因为它们依赖于私有字段和静态类块等特性。

第三步：编写对应的装饰器代码

配置文件确定后，必须编写与之对应的代码语法。混合使用配置与语法会导致编译错误。

1. 旧版装饰器语法

在旧版模式下，装饰器本质上是一个函数，它接收目标对象作为参数。

1. 定义一个名为 Log 的装饰器工厂。
2. 应用装饰器到类或方法上。

// 旧版装饰器定义
function Log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;
  descriptor.value = function (...args: any[]) {
    console.log(`Method ${propertyKey} called`);
    return originalMethod.apply(this, args);
  };
}

class UserService {
  @Log
  getUser(id: number) {
    return { id, name: "Alice" };
  }
}
```

#### 2. 新版装饰器语法

在新版模式下，装饰器函数接收一个“装饰器上下文”对象，且语法支持 `accessor` 关键字来自动生成 getter/setter。

1.  **定义**一个新版装饰器。
2.  **利用** `context` 对象获取元信息。
3.  **使用** `@accessor` 装饰类字段。

```typescript
// 新版装饰器定义
function Log(value: any, context: ClassMethodDecoratorContext) {
  const methodName = String(context.name);
  context.addInitializer(function () {
    console.log(`Method ${methodName} initialized`);
  });
}

class ProductService {
  @Log
  getItem(id: number) {
    return { id, name: "Product A" };
  }

  // 使用新版特有的 accessor 装饰器
  @accessor
  status: string = "active";
}

第四步：排查常见错误

在开发过程中，遇到编译错误通常是因为配置与语法不匹配。以下是快速排查流程。

检查以下关键点以确保代码正常运行。

1. 验证 target 版本：
   若使用新版装饰器，确保 tsconfig.json 中的 target 不低于 ES2022。否则，编译器可能无法识别新版语法特性。

2. 确认 emitDecoratorMetadata：
   如果使用依赖反射的库（如 class-transformer 或 routing-controllers），必须确保 emitDecoratorMetadata 设置为 true，否则运行时类型信息为空。

3. 区分 装饰器类型返回值：

   • 在旧版中，方法装饰器必须返回 PropertyDescriptor 或 void。
   • 在新版中，方法装饰器返回的函数会在调用方法前执行。

第五步：迁移建议（从旧版到新版）

如果决定将现有项目迁移至新版装饰器，请执行以下步骤。

1. 备份现有的 tsconfig.json 配置。
2. 修改 experimentalDecorators 为 false。
3. 逐个修改装饰器函数签名：
   将 (target, key, descriptor) 改为 (value, context)。
4. 替换 @property 装饰器：
   如果旧代码通过属性描述符修改属性，需考虑使用新版中的 accessor 关键字重写逻辑。
5. 升级第三方库：
   确认依赖的框架（如 NestJS 或 Angular）已支持新版装饰器标准，否则无法完成编译。

配置与特性对比表

通过严格区分 tsconfig.json 中的配置选项与对应的代码语法，即可彻底解决 TypeScript 装饰器的编译与运行问题。