M

MLOG

中文

探索 TypeScript 装饰器：一种强大的元编程功能，可用于增强代码结构、可重用性和可维护性。通过实际示例学习如何有效利用它们。

TypeScript 装饰器：释放元编程的力量

TypeScript 装饰器提供了一种强大而优雅的方式，通过元编程能力来增强您的代码。它们提供了一种在设计时修改和扩展类、方法、属性和参数的机制，允许您在不改变代码核心逻辑的情况下注入行为和注解。本博客文章将深入探讨 TypeScript 装饰器的复杂性，为各级开发人员提供全面的指南。我们将探讨什么是装饰器、它们如何工作、可用的不同类型、实际示例以及有效使用的最佳实践。无论您是 TypeScript 新手还是经验丰富的开发人员，本指南都将为您提供利用装饰器编写更清晰、更易于维护和更具表现力的代码所需的知识。

什么是 TypeScript 装饰器？

从本质上讲，TypeScript 装饰器是元编程的一种形式。它们实际上是函数，接受一个或多个参数（通常是被装饰的对象，如类、方法、属性或参数），并可以修改它或添加新功能。可以把它们看作是附加到代码上的注解或属性。这些注解可以用来提供关于代码的元数据，或者改变其行为。

装饰器使用 `@` 符号后跟一个函数调用来定义（例如，`@decoratorName()`）。然后，装饰器函数将在应用程序的设计时阶段执行。

装饰器的灵感来源于 Java、C# 和 Python 等语言中的类似功能。它们提供了一种分离关注点和促进代码重用性的方法，通过将核心逻辑保持整洁，并将元数据或修改方面集中在一个专门的地方。

装饰器如何工作

TypeScript 编译器将装饰器转换为在设计时调用的函数。传递给装饰器函数的具体参数取决于所使用的装饰器类型（类、方法、属性或参数）。让我们来分解不同类型的装饰器及其各自的参数：

理解这些参数签名对于编写有效的装饰器至关重要。

装饰器的类型

TypeScript 支持多种类型的装饰器，每种都有其特定用途：

实际示例

让我们探索一些实际示例，以说明如何在 TypeScript 中使用装饰器。

类装饰器示例：添加时间戳

假设您想为每个类的实例添加一个时间戳。您可以使用类装饰器来完成此任务：


function addTimestamp<T extends { new(...args: any[]): {} }>(constructor: T) {
  return class extends constructor {
    timestamp = Date.now();
  };
}

@addTimestamp
class MyClass {
  constructor() {
    console.log('MyClass created');
  }
}

const instance = new MyClass();
console.log(instance.timestamp); // 输出：一个时间戳

在此示例中，`addTimestamp` 装饰器向类实例添加了一个 `timestamp` 属性。这提供了有价值的调试或审计追踪信息，而无需直接修改原始类定义。

方法装饰器示例：记录方法调用

您可以使用方法装饰器来记录方法调用及其参数：


function logMethod(target: any, key: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;

  descriptor.value = function (...args: any[]) {
    console.log(`[LOG] Method ${key} called with arguments:`, args);
    const result = originalMethod.apply(this, args);
    console.log(`[LOG] Method ${key} returned:`, result);
    return result;
  };

  return descriptor;
}

class Greeter {
  @logMethod
  greet(message: string): string {
    return `Hello, ${message}!`;
  }
}

const greeter = new Greeter();
greeter.greet('World');
// 输出：
// [LOG] Method greet called with arguments: [ 'World' ]
// [LOG] Method greet returned: Hello, World!

此示例记录了每次调用 `greet` 方法的时间、其参数和返回值。这对于在更复杂的应用程序中进行调试和监控非常有用。

属性装饰器示例：添加验证

这是一个添加基本验证的属性装饰器示例：


function validate(target: any, key: string) {
  let value: any;

  const getter = function () {
    return value;
  };

  const setter = function (newValue: any) {
    if (typeof newValue !== 'number') {
      console.warn(`[WARN] Invalid property value: ${key}. Expected a number.`);
      return;
    }
    value = newValue;
  };

  Object.defineProperty(target, key, {
    get: getter,
    set: setter,
    enumerable: true,
    configurable: true,
  });
}

class Person {
  @validate
  age: number; //  <- 带有验证的属性
}

const person = new Person();
person.age = 'abc'; // 记录一条警告
person.age = 30;   // 设置值
console.log(person.age); // 输出: 30

在此 `validate` 装饰器中，我们检查赋的值是否为数字。如果不是，则记录一条警告。这是一个简单的示例，但它展示了如何使用装饰器来强制实现数据完整性。

参数装饰器示例：依赖注入（简化版）

虽然功能齐全的依赖注入框架通常使用更复杂的机制，但装饰器也可用于标记要注入的参数。此示例是一个简化的说明：


// 这是一个简化版，并未处理实际的注入。真正的依赖注入更为复杂。
function Inject(service: any) {
  return function (target: any, propertyKey: string | symbol, parameterIndex: number) {
    // 将服务存储在某处（例如，静态属性或 Map 中）
    if (!target.injectedServices) {
      target.injectedServices = {};
    }
    target.injectedServices[parameterIndex] = service;
  };
}

class MyService {
  doSomething() { /* ... */ }
}

class MyComponent {
  constructor(@Inject(MyService) private myService: MyService) {
    // 在实际系统中，DI 容器会在这里解析 'myService'。
    console.log('MyComponent constructed with:', myService.constructor.name); //示例
  }
}

const component = new MyComponent(new MyService());  // 注入服务（简化版）。

`Inject` 装饰器将一个参数标记为需要一个服务。此示例演示了装饰器如何识别需要依赖注入的参数（但真正的框架需要管理服务解析）。

使用装饰器的好处

使用装饰器的最佳实践

高级概念

装饰器工厂

装饰器工厂是返回装饰器函数的函数。这允许您向装饰器传递参数，使它们更加灵活和可配置。例如，您可以创建一个验证装饰器工厂，允许您指定验证规则：


function validate(minLength: number) {
  return function (target: any, key: string) {
    let value: string;

    const getter = function () {
      return value;
    };

    const setter = function (newValue: string) {
      if (typeof newValue !== 'string') {
        console.warn(`[WARN] Invalid property value: ${key}. Expected a string.`);
        return;
      }
      if (newValue.length < minLength) {
        console.warn(`[WARN] ${key} must be at least ${minLength} characters long.`);
        return;
      }
      value = newValue;
    };

    Object.defineProperty(target, key, {
      get: getter,
      set: setter,
      enumerable: true,
      configurable: true,
    });
  };
}

class Person {
  @validate(3) // 使用最小长度 3 进行验证
  name: string;
}

const person = new Person();
person.name = 'Jo';
console.log(person.name); // 记录一条警告，并设置值。
person.name = 'John';
console.log(person.name); // 输出: John

装饰器工厂使装饰器更具适应性。

组合装饰器

您可以将多个装饰器应用于同一元素。它们的应用顺序有时可能很重要。顺序是自下而上（按书写顺序）。例如：


function first() {
  console.log('first(): factory evaluated');
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    console.log('first(): called');
  }
}

function second() {
  console.log('second(): factory evaluated');
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    console.log('second(): called');
  }
}

class ExampleClass {
  @first()
  @second()
  method() {}
}

// 输出：
// second(): factory evaluated
// first(): factory evaluated
// second(): called
// first(): called

请注意，工厂函数按其出现的顺序进行评估，但装饰器函数按相反的顺序调用。如果您的装饰器相互依赖，请理解此顺序。

装饰器与元数据反射

装饰器可以与元数据反射（例如，使用像 `reflect-metadata` 这样的库）协同工作，以获得更动态的行为。这使您能够在运行时存储和检索有关被装饰元素的信息。这在框架和依赖注入系统中特别有用。装饰器可以用元数据注解类或方法，然后可以使用反射来发现和使用该元数据。

流行框架和库中的装饰器

装饰器已成为许多现代 JavaScript 框架和库的组成部分。了解它们的应用有助于您理解框架的架构以及它如何简化各种任务。

这些框架和库展示了装饰器如何在实际应用中增强代码组织、简化常见任务并促进可维护性。

挑战与考量

结论

TypeScript 装饰器是一种强大的元编程功能，可以显著改善代码的结构、可重用性和可维护性。通过理解不同类型的装饰器、它们的工作原理以及使用的最佳实践，您可以利用它们来创建更清晰、更具表现力和更高效的应用程序。无论您是在构建简单的应用程序还是复杂的企业级系统，装饰器都为增强您的开发工作流程提供了宝贵的工具。拥抱装饰器可以显著提高代码质量。通过了解装饰器如何集成到 Angular 和 NestJS 等流行框架中，开发人员可以充分利用其潜力来构建可扩展、可维护和健壮的应用程序。关键在于理解其目的以及如何在适当的上下文中应用它们，确保其好处大于任何潜在的缺点。

通过有效地实施装饰器，您可以以更高的结构性、可维护性和效率来增强您的代码。本指南全面概述了如何使用 TypeScript 装饰器。有了这些知识，您就有能力创建更好、更易于维护的 TypeScript 代码。去尽情地装饰吧！