reflect-metadata 是一个用于 JavaScript（包括 TypeScript）的库，它提供了一种标准化的方式来定义和读取元数据。元数据是在运行时可以访问的数据，这些数据描述了类、类成员（如属性和方法）、参数等的信息。reflect-metadata 主要用于支持装饰器（Decorators），这是一种特殊的语法，允许你在类声明或成员声明上添加注解和元数据。

安装

在使用 reflect-metadata 之前，你需要先通过 npm 安装它：

npm install reflect-metadata

对于 TypeScript 项目，还需要确保在 tsconfig.json 文件中启用 experimentalDecorators 和 emitDecoratorMetadata 选项：

{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

基本用法

定义元数据

你可以使用 Reflect.defineMetadata 方法来定义元数据：

import 'reflect-metadata';

class Example {
  @Reflect.metadata('description', '这是一个示例方法')
  method() {}
}

const method = Example.prototype.method;
console.log(Reflect.getMetadata('description', method)); // 输出: 这是一个示例方法

在这个例子中，我们为 Example 类中的 method 方法定义了一个名为 description 的元数据项，其值为 '这是一个示例方法'。

获取元数据

使用 Reflect.getMetadata 方法可以获取之前定义的元数据：

import 'reflect-metadata';

function log(target: any, key: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;
  descriptor.value = function(...args: any[]) {
    console.log(`调用了 ${key} 方法`);
    return originalMethod.apply(this, args);
  };
  Reflect.defineMetadata('description', '这是一个被装饰的方法', descriptor.value);
}

class Example {
  @log
  method() {
    console.log('执行方法');
  }
}

const example = new Example();
example.method(); // 调用了 method 方法\n执行方法
console.log(Reflect.getMetadata('description', example.method)); // 这是一个被装饰的方法

这里，我们创建了一个装饰器 log，它不仅修改了方法的行为，还在该方法上定义了一个元数据项。

其他方法

reflect-metadata 还提供了其他一些方法来操作元数据，比如：

• Reflect.hasMetadata(key: any, target: Object, [propertyKey: string | symbol]): boolean - 检查目标对象是否具有指定键的元数据。
• Reflect.deleteMetadata(key: any, target: Object, [propertyKey: string | symbol]): boolean - 删除目标对象上的指定元数据项。
• Reflect.getOwnMetadata(key: any, target: Object, [propertyKey: string | symbol]): any - 获取目标对象自身上的元数据，不包括继承的元数据。

高级特性

元数据键的命名规范

为了防止元数据键冲突，通常建议使用字符串作为键，并且包含一些前缀或命名空间。例如：

import 'reflect-metadata';

const METADATA_KEY_DESCRIPTION = 'myapp:description';

class Example {
  @Reflect.metadata(METADATA_KEY_DESCRIPTION, '这是一个示例方法')
  method() {}
}

const method = Example.prototype.method;
console.log(Reflect.getMetadata(METADATA_KEY_DESCRIPTION, method)); // 输出: 这是一个示例方法

继承元数据

当一个类继承另一个类时，子类会继承父类上的元数据。但是，只有使用 Reflect.getMetadata 获取元数据时才会考虑到继承关系。Reflect.getOwnMetadata 只会返回目标对象自身的元数据，不会考虑继承的元数据。

import 'reflect-metadata';

class Base {
  @Reflect.metadata('description', '基类方法')
  method() {}
}

class Derived extends Base {
  @Reflect.metadata('description', '派生类方法')
  method() {}
}

const derivedInstance = new Derived();
console.log(Reflect.getMetadata('description', derivedInstance, 'method')); // 输出: 派生类方法
console.log(Reflect.getOwnMetadata('description', derivedInstance, 'method')); // 输出: 派生类方法
console.log(Reflect.getMetadata('description', new Base(), 'method')); // 输出: 基类方法

参数元数据

除了类和方法级别的元数据，reflect-metadata 还支持参数级别的元数据。这对于依赖注入特别有用。

import 'reflect-metadata';

function inject(target: any, key: string, index: number) {
  let existingParams = Reflect.getMetadata('design:paramtypes', target, key) || [];
  existingParams[index] = String; // 假设我们希望注入一个字符串类型的参数
  Reflect.defineMetadata('design:paramtypes', existingParams, target, key);
}

class Service {}

class Example {
  constructor(@inject private service: Service) {}

  @Reflect.metadata('description', '示例方法')
  method(@inject param: string) {
    console.log(param);
  }
}

const example = new Example(new Service());
example.method('Hello, World!'); // 输出: Hello, World!

应用场景

依赖注入

在许多现代框架中，依赖注入是一个常见的设计模式。reflect-metadata 可以帮助实现依赖注入，尤其是在 TypeScript 项目中。

import 'reflect-metadata';

class DatabaseService {}

class UserService {
  constructor(private db: DatabaseService) {}
}

class App {
  constructor(private userService: UserService) {}
}

// 注册服务
const services = new Map();
services.set(DatabaseService, new DatabaseService());
services.set(UserService, new UserService(services.get(DatabaseService)));
services.set(App, new App(services.get(UserService)));

const app = services.get(App);

路由配置

在 Web 框架中，路由配置通常需要大量的元数据来描述每个路由的行为。reflect-metadata 可以简化这一过程。

import 'reflect-metadata';

function Get(path: string) {
  return (target: any, key: string, descriptor: PropertyDescriptor) => {
    Reflect.defineMetadata('path', path, descriptor.value);
  };
}

class UserController {
  @Get('/users')
  listUsers() {
    console.log('列出所有用户');
  }

  @Get('/users/:id')
  getUser(id: string) {
    console.log(`获取用户 ${id}`);
  }
}

const controller = new UserController();
const methods = Object.getOwnPropertyNames(UserController.prototype)
  .filter(name => name !== 'constructor')
  .map(name => ({
    name,
    path: Reflect.getMetadata('path', UserController.prototype[name])
  }));

methods.forEach(method => {
  console.log(`路由: ${method.path} -> 方法: ${method.name}`);
});

数据验证

在表单验证或其他需要对输入数据进行验证的场景中，reflect-metadata 可以用来存储和读取验证规则。

import 'reflect-metadata';

const METADATA_KEY_VALIDATION_RULES = 'validation:rules';

function MinLength(length: number) {
  return (target: any, key: string) => {
    let rules = Reflect.getMetadata(METADATA_KEY_VALIDATION_RULES, target, key) || [];
    rules.push({ type: 'minLength', value: length });
    Reflect.defineMetadata(METADATA_KEY_VALIDATION_RULES, rules, target, key);
  };
}

class User {
  @MinLength(3)
  name: string;

  constructor(name: string) {
    this.name = name;
  }
}

const user = new User('Jo');
const rules = Reflect.getMetadata(METADATA_KEY_VALIDATION_RULES, user, 'name');

if (rules) {
  for (const rule of rules) {
    if (rule.type === 'minLength' && user.name.length < rule.value) {
      console.log(`名称长度必须至少为 ${rule.value} 个字符`);
    }
  }
}

总结

reflect-metadata 是一个非常强大的工具，可以在多种场景下提高代码的灵活性和可维护性。通过合理使用元数据，可以简化复杂的逻辑，使代码更加清晰和模块化。然而，需要注意的是，元数据的使用可能会增加应用的复杂性和运行时开销，因此在实际项目中应权衡利弊，合理使用。