TypeScript装饰器原理与应用实践指南

1. TypeScript 装饰器深度解析

TypeScript 装饰器是近年来前端开发中越来越重要的元编程工具。作为一名长期使用 TypeScript 进行企业级应用开发的工程师，我发现装饰器能显著提升代码的可维护性和可扩展性。本文将带你深入理解装饰器的原理、应用场景和最佳实践。

装饰器本质上是一种特殊类型的声明，可以附加到类声明、方法、访问器、属性或参数上。它的核心价值在于能够将横切关注点（如日志、验证、缓存等）从业务逻辑中分离出来，实现代码的声明式复用。

1.1 装饰器基础配置

要使用装饰器，首先需要在 tsconfig.json 中启用相关配置：

json复制{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "target": "ES5"
  }
}

这里有几个关键点需要注意：

• experimentalDecorators：必须设置为 true 才能使用装饰器语法
• emitDecoratorMetadata：启用元数据发射，这对依赖注入等高级用法很重要
• target：建议至少设置为 ES5，因为装饰器需要一些 ES5 的特性支持

1.2 装饰器类型概览

TypeScript 支持五种主要类型的装饰器：

1.3 装饰器执行顺序详解

理解装饰器的执行顺序至关重要，特别是在多个装饰器组合使用时。装饰器的执行分为两个阶段：

1.3.1 工厂函数执行阶段

装饰器工厂函数（即返回装饰器函数的函数）按照从上到下、从外到内的顺序执行：

typescript复制function A() {
  console.log('1. 工厂 A 被调用');
  return function (target: any) {
    console.log('4. 装饰器 A 被执行');
  };
}

function B() {
  console.log('2. 工厂 B 被调用');
  return function (target: any) {
    console.log('3. 装饰器 B 被执行');
  };
}

@A()
@B()
class Example {}

输出顺序将是：

1. 工厂 A 被调用
2. 工厂 B 被调用
3. 装饰器 B 被执行
4. 装饰器 A 被执行

1.3.2 类成员装饰器的完整顺序

对于类成员的装饰器，执行顺序更加复杂：

typescript复制function ClassDec() {
  console.log('① 类装饰器工厂');
  return function (target: any) {
    console.log('⑥ 类装饰器执行');
  };
}

function PropDec() {
  console.log('② 属性装饰器工厂');
  return function (target: any, key: string) {
    console.log('④ 属性装饰器执行');
  };
}

function MethodDec() {
  console.log('③ 方法装饰器工厂');
  return function (target: any, key: string, descriptor: PropertyDescriptor) {
    console.log('⑤ 方法装饰器执行');
  };
}

@ClassDec()
class Example {
  @PropDec()
  name: string;

  @MethodDec()
  method() {}
}

完整执行顺序为：

1. 类装饰器工厂（最外层）
2. 属性装饰器工厂
3. 方法装饰器工厂
4. 属性装饰器执行
5. 方法装饰器执行
6. 类装饰器执行（最内层）

1.3.3 同一声明上的多个装饰器

当同一个声明上有多个装饰器时：

typescript复制function First() {
  console.log('工厂 First');
  return function (target: any, key: string, descriptor: PropertyDescriptor) {
    console.log('装饰器 First 执行');
  };
}

function Second() {
  console.log('工厂 Second');
  return function (target: any, key: string, descriptor: PropertyDescriptor) {
    console.log('装饰器 Second 执行');
  };
}

class Example {
  @First()
  @Second()
  method() {}
}

输出顺序为：

1. 工厂 First
2. 工厂 Second
3. 装饰器 Second 执行
4. 装饰器 First 执行

这相当于：

typescript复制method = First(Second(
  Object.getOwnPropertyDescriptor(Example.prototype, 'method')
));

1.4 装饰器执行顺序总结

记忆口诀：

code复制工厂从上走到下
装饰从下往上挂
方法调用先外层
层层包裹像穿褂

2. 属性装饰器深度应用

属性装饰器在类属性声明之前被声明，它接收两个参数：

1. 对于静态成员是类的构造函数，对于实例成员是类的原型对象
2. 成员的名字

2.1 基本语法

typescript复制function PropertyDecorator(target: any, key: string) {
  // target: 实例属性为原型对象，静态属性为构造函数
  // key: 属性名字符串
}

2.2 依赖注入实战

依赖注入是属性装饰器的典型应用场景：

typescript复制import "reflect-metadata";

function Inject(target: any, key: string) {
  const type = Reflect.getMetadata("design:type", target, key);
  target[key] = new type();
}

class Logger {
  log(message: string) {
    console.log(`[LOG] ${message}`);
  }
}

class UserService {
  @Inject
  logger!: Logger; // ! 表示"我会确保这个属性被赋值"

  createUser() {
    this.logger.log("用户创建成功");
  }
}

new UserService().createUser();
// 输出: [LOG] 用户创建成功

这里有几个关键点：

1. 使用 reflect-metadata 获取属性的类型信息
2. ! 是确定赋值断言，告诉 TypeScript 这个属性会被确保赋值
3. 装饰器在类实例化前就已经完成了依赖注入

2.3 属性验证装饰器

属性装饰器也可以用于验证：

typescript复制function Validate(rule: { minLength?: number; pattern?: RegExp }) {
  return function (target: any, key: string) {
    let value: any;
    Object.defineProperty(target, key, {
      get: () => value,
      set: (newValue: any) => {
        if (rule.minLength && newValue?.length < rule.minLength) {
          throw new Error(`${key} 长度不能少于 ${rule.minLength}`);
        }
        if (rule.pattern && !rule.pattern.test(newValue)) {
          throw new Error(`${key} 格式不正确`);
        }
        value = newValue;
      },
    });
  };
}

class User {
  @Validate({ minLength: 3, pattern: /^[a-zA-Z]+$/ })
  name!: string;
}

const user = new User();
user.name = "Jo"; // ❌ 抛出错误: name 长度不能少于 3

这种验证方式比在方法中手动验证更加优雅和可复用。

3. 方法装饰器高级用法

方法装饰器可以观察、修改或替换方法定义，它接收三个参数：

1. 对于静态成员是类的构造函数，对于实例成员是类的原型对象
2. 成员的名字
3. 成员的属性描述符

3.1 基本语法

typescript复制function MethodDecorator(
  target: any, // 实例方法：原型对象；静态方法：构造函数
  key: string, // 方法名
  descriptor: PropertyDescriptor, // 方法描述符
) {
  const original = descriptor.value;
  descriptor.value = function (...args: any[]) {
    // 修改方法行为
    return original.apply(this, args);
  };
}

3.2 日志装饰器实现

typescript复制function Log(target: any, key: string, descriptor: PropertyDescriptor) {
  const original = descriptor.value;
  descriptor.value = function (...args: any[]) {
    console.log(`[LOG] ${key} 被调用，参数:`, args);
    const result = original.apply(this, args);
    console.log(`[LOG] ${key} 返回:`, result);
    return result;
  };
}

class Calculator {
  @Log
  add(a: number, b: number): number {
    return a + b;
  }
}

new Calculator().add(1, 2);
// [LOG] add 被调用，参数: [1, 2]
// [LOG] add 返回: 3

3.3 防抖装饰器实现

防抖是前端开发中常见的需求：

typescript复制function Debounce(delay: number) {
  return function (target: any, key: string, descriptor: PropertyDescriptor) {
    const original = descriptor.value;
    let timer: NodeJS.Timeout | null = null;

    descriptor.value = function (...args: any[]) {
      if (timer) clearTimeout(timer);
      timer = setTimeout(() => original.apply(this, args), delay);
    };
  };
}

class SearchBox {
  query = "";

  @Debounce(300)
  search() {
    console.log("搜索:", this.query);
  }
}

3.4 缓存装饰器实现

缓存可以显著提升性能：

typescript复制function Cache(ttl?: number) {
  return function (target: any, key: string, descriptor: PropertyDescriptor) {
    const original = descriptor.value;
    const cache = new Map<string, { value: any; expiry: number }>();

    descriptor.value = function (...args: any[]) {
      const cacheKey = JSON.stringify(args);
      const cached = cache.get(cacheKey);

      if (cached && (!ttl || Date.now() < cached.expiry)) {
        console.log("从缓存返回");
        return cached.value;
      }

      const result = original.apply(this, args);
      cache.set(cacheKey, {
        value: result,
        expiry: ttl ? Date.now() + ttl : Number.MAX_VALUE,
      });
      return result;
    };
  };
}

class MathService {
  @Cache(5000) // 缓存5秒
  fibonacci(n: number): number {
    console.log("计算 fibonacci");
    if (n <= 1) return n;
    return this.fibonacci(n - 1) + this.fibonacci(n - 2);
  }
}

3.5 重试装饰器实现

对于不稳定的操作，重试机制很有用：

typescript复制function Retry(maxAttempts: number = 3, delay: number = 1000) {
  return function (target: any, key: string, descriptor: PropertyDescriptor) {
    const original = descriptor.value;
    descriptor.value = async function (...args: any[]) {
      let lastError: any;

      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
        try {
          return await original.apply(this, args);
        } catch (error) {
          lastError = error;
          if (attempt < maxAttempts) {
            await new Promise((resolve) => setTimeout(resolve, delay));
          }
        }
      }

      throw new Error(`${key} 失败 ${maxAttempts} 次后放弃`);
    };
  };
}

class ApiService {
  @Retry(3, 1000)
  async fetchData(url: string) {
    const response = await fetch(url);
    if (!response.ok) throw new Error("请求失败");
    return response.json();
  }
}

4. 装饰器工厂与组合

装饰器工厂是一个返回装饰器函数的函数，用于传递自定义参数。

4.1 基本模式

typescript复制function DecoratorFactory(config: any) {
  return function (target: any, key: string, descriptor: PropertyDescriptor) {
    // 使用 config 定制装饰器行为
  };
}

class Example {
  @DecoratorFactory({ option: 'value' })
  method() {}
}

4.2 装饰器组合

多个装饰器可以组合使用：

typescript复制class UserService {
  @Log()
  @Validate({ name: "string" })
  @Catch((error) => console.error(error))
  createUser(name: string) {
    // 先执行 Catch，再 Validate，最后 Log
  }
}

4.3 组合装饰器工具函数

可以创建一个组合装饰器的工具函数：

typescript复制function Compose(...decorators: PropertyDecorator[]) {
  return function (
    target: any,
    key: string,
    descriptor: PropertyDescriptor,
  ) {
    decorators.forEach((decorator) => decorator(target, key, descriptor));
  };
}

class Example {
  @Compose(Log(), Validate(), Catch())
  method() {}
}

5. 实际应用场景

5.1 NestJS 风格依赖注入

typescript复制import "reflect-metadata";

const Injectable = () => (_target: any) => {};

const constructors = new Map<string, any>();

function Inject(token?: string) {
  return function (target: any, key: string) {
    const type = Reflect.getMetadata("design:type", target, key);
    const dependencyToken = token || type.name;

    Object.defineProperty(target, key, {
      get() {
        if (!constructors.has(dependencyToken)) {
          throw new Error(`依赖 ${dependencyToken} 未注册`);
        }
        return constructors.get(dependencyToken);
      },
      set(value) {
        constructors.set(dependencyToken, value);
      },
    });
  };
}

@Injectable()
class Logger {
  log(message: string) {
    console.log(`[LOG] ${message}`);
  }
}

@Injectable()
class Database {
  connect() {
    console.log("[DB] 连接数据库");
  }
}

class UserService {
  @Inject()
  logger!: Logger;

  @Inject()
  db!: Database;

  createUser() {
    this.logger.log("创建用户");
    this.db.connect();
  }
}

// 注册依赖
constructors.set("Logger", new Logger());
constructors.set("Database", new Database());

new UserService().createUser();
// [LOG] 创建用户
// [DB] 连接数据库

5.2 API 路由装饰器

typescript复制const ROUTES: Array<{
  path: string;
  method: string;
  handler: Function;
}> = [];

function Controller(prefix: string) {
  return function <T extends { new (...args: any[]): {} }>(constructor: T) {
    return class extends constructor {
      constructor(...args: any[]) {
        super(...args);
        console.log(`📦 控制器注册: ${prefix}`);
      }
    };
  };
}

function Get(path: string) {
  return function (target: any, key: string, descriptor: PropertyDescriptor) {
    ROUTES.push({
      path,
      method: "GET",
      handler: descriptor.value,
    });
  };
}

function Post(path: string) {
  return function (target: any, key: string, descriptor: PropertyDescriptor) {
    ROUTES.push({
      path,
      method: "POST",
      handler: descriptor.value,
    });
  };
}

@Controller("/api/users")
class UserController {
  @Get("/:id")
  getUser(id: string) {
    return { id, name: "用户详情" };
  }

  @Post("/")
  createUser(data: any) {
    return { success: true, data };
  }
}

console.log("📋 已注册的路由:", ROUTES);

5.3 ORM 实体定义

typescript复制interface ColumnMetadata {
  type: "string" | "number" | "boolean" | "date";
  primary?: boolean;
  nullable?: boolean;
  length?: number;
}

const entityMetadata = new Map<Function, Map<string, ColumnMetadata>>();

function Entity(tableName: string) {
  return function (constructor: Function) {
    console.log(`📊 实体表名: ${tableName}`);
  };
}

function Column(options: ColumnMetadata) {
  return function (target: any, key: string) {
    if (!entityMetadata.has(target.constructor)) {
      entityMetadata.set(target.constructor, new Map());
    }
    entityMetadata.get(target.constructor)!.set(key, options);
  };
}

@Entity("users")
class User {
  @Column({ type: "number", primary: true })
  id!: number;

  @Column({ type: "string", length: 100 })
  name!: string;

  @Column({ type: "string", length: 255, nullable: true })
  email!: string | null;

  @Column({ type: "boolean", nullable: false })
  isActive!: boolean;
}

const userMetadata = entityMetadata.get(User);
console.log("📋 User 实体元数据:", userMetadata);

5.4 表单验证系统

typescript复制interface ValidationRule {
  required?: boolean;
  minLength?: number;
  maxLength?: number;
  pattern?: RegExp;
  custom?: (value: any) => boolean | string;
}

const validations = new Map<Object, Map<string, ValidationRule[]>>();

function Validate(rules: ValidationRule | ValidationRule[]) {
  return function (target: any, key: string) {
    const ruleArray = Array.isArray(rules) ? rules : [rules];

    if (!validations.has(target)) {
      validations.set(target, new Map());
    }
    validations.get(target)!.set(key, ruleArray);

    let value: any;

    return {
      get() {
        return value;
      },
      set(newValue: any) {
        const errors: string[] = [];

        for (const rule of ruleArray) {
          if (rule.required && !newValue) {
            errors.push(`${key} 是必填项`);
          }
          if (rule.minLength && newValue?.length < rule.minLength) {
            errors.push(`${key} 长度不能少于 ${rule.minLength}`);
          }
          if (rule.maxLength && newValue?.length > rule.maxLength) {
            errors.push(`${key} 长度不能超过 ${rule.maxLength}`);
          }
          if (rule.pattern && !rule.pattern.test(newValue)) {
            errors.push(`${key} 格式不正确`);
          }
          if (rule.custom) {
            const result = rule.custom(newValue);
            if (result !== true) {
              errors.push(result as string);
            }
          }
        }

        if (errors.length > 0) {
          console.error(`❌ 验证失败 (${key}):`, errors.join(", "));
          throw new Error(errors.join(", "));
        }

        value = newValue;
      },
    };
  };
}

class RegisterForm {
  @Validate({
    required: true,
    minLength: 3,
    maxLength: 20,
    pattern: /^[a-zA-Z0-9_]+$/,
  })
  username!: string;

  @Validate({
    required: true,
    pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
  })
  email!: string;

  @Validate([
    { required: true, minLength: 8 },
    {
      custom: (value) => /[A-Z]/.test(value) || "密码必须包含大写字母",
    },
    {
      custom: (value) => /[a-z]/.test(value) || "密码必须包含小写字母",
    },
    {
      custom: (value) => /[0-9]/.test(value) || "密码必须包含数字",
    },
  ])
  password!: string;
}

6. 装饰器最佳实践

6.1 应该遵循的原则

1. 保持装饰器简单专注：每个装饰器应该只做一件事
2. 使用装饰器工厂提供参数：使装饰器更加灵活
3. 支持装饰器组合：多个简单装饰器比一个复杂装饰器更好
4. 提供类型安全：利用 TypeScript 的类型系统
5. 文档化装饰器行为：明确说明装饰器的用途和参数

6.2 应该避免的反模式

1. 不要在装饰器中执行副作用：装饰器应该在类定义时执行，而不是运行时
2. 不要修改装饰器目标的结构：避免直接修改原型链
3. 不要忘记保持this绑定：确保方法调用时的上下文正确
4. 不要忽略错误处理：装饰器应该优雅地处理错误

6.3 性能考虑

装饰器在类定义时执行，通常不会影响运行时性能。但是：

1. 复杂的装饰器逻辑可能增加启动时间
2. 反射操作（如 reflect-metadata）可能有性能开销
3. 装饰器创建的闭包会增加内存使用

在实际项目中，应该对装饰器的性能影响进行评估，特别是在大型应用中。

7. 装饰器的高级主题

7.1 元数据反射

reflect-metadata 是装饰器的核心依赖，提供了运行时类型反射能力：

typescript复制import "reflect-metadata";

class Example {
  @Reflect.metadata("design:type", String)
  name: string;

  @Reflect.metadata("design:paramtypes", [String, Number])
  method(param1: string, param2: number) {}
}

const type = Reflect.getMetadata("design:type", Example.prototype, "name");
const paramTypes = Reflect.getMetadata("design:paramtypes", Example.prototype, "method");

console.log(type); // [Function: String]
console.log(paramTypes); // [ [Function: String], [Function: Number] ]

7.2 装饰器与继承

装饰器在继承链中的行为：

typescript复制function Log(target: any, key: string) {
  console.log(`装饰器应用于 ${target.constructor.name}.${key}`);
}

class Parent {
  @Log
  method() {}
}

class Child extends Parent {
  @Log
  method() {}
}

// 输出:
// 装饰器应用于 Parent.method
// 装饰器应用于 Child.method

7.3 装饰器与 this 绑定

确保装饰器不破坏方法的 this 绑定：

typescript复制function BadDecorator(target: any, key: string, descriptor: PropertyDescriptor) {
  const original = descriptor.value;
  descriptor.value = function (...args: any[]) {
    return original(...args); // ❌ 错误的 this 绑定
  };
}

function GoodDecorator(target: any, key: string, descriptor: PropertyDescriptor) {
  const original = descriptor.value;
  descriptor.value = function (...args: any[]) {
    return original.apply(this, args); // ✅ 正确的 this 绑定
  };
}

7.4 装饰器与异步方法

正确处理异步方法：

typescript复制function AsyncDecorator(target: any, key: string, descriptor: PropertyDescriptor) {
  const original = descriptor.value;
  descriptor.value = async function (...args: any[]) {
    try {
      console.time(key);
      const result = await original.apply(this, args);
      console.timeEnd(key);
      return result;
    } catch (error) {
      console.error(`${key} 执行失败:`, error);
      throw error;
    }
  };
}

class Example {
  @AsyncDecorator
  async fetchData() {
    // 异步操作
  }
}

8. 装饰器的局限性与替代方案

8.1 当前限制

1. Stage 2 提案：装饰器目前仍是 ECMAScript 的 Stage 2 提案
2. 元数据限制：类型信息在编译后会丢失
3. 调试困难：装饰器转换的代码可能难以调试

8.2 替代方案

1. 高阶函数：对于简单场景，可以使用普通的高阶函数
2. 中间件模式：对于横切关注点，中间件可能是更好的选择
3. AOP 框架：成熟的 AOP 框架提供更强大的功能

8.3 未来发展方向

1. ECMAScript 标准进展：装饰器提案正在推进
2. 更强大的元编程能力：未来可能会有更多的反射 API
3. 更好的工具链支持：调试和性能分析工具的改进

在实际项目中采用装饰器时，应该权衡其带来的便利性和潜在的风险，特别是在大型长期维护的项目中。