JS `Reflect.metadata` (提案)：为类、方法、属性添加元数据

大家好，欢迎来到今天的元数据魔法课堂！我是你们的魔法师，今天我们要一起探索 JavaScript 中一个相当有趣，但又经常被忽略的提案：Reflect.metadata。 准备好一起挖掘元数据的宝藏了吗？Let’s dive in!

什么是元数据？为什么要关心它？

想象一下，你有一个快递包裹。包裹里面装的是实际的数据（比如你的新书）。元数据就像包裹上的标签、运单号、发货人信息等等。它描述了数据本身，而不是数据的内容。

在编程世界里，元数据就是描述代码的代码！它能告诉你关于类、方法、属性的额外信息，这些信息不是通过代码本身就能直接看出来的。

你可能会问：“我为什么要关心这些标签？我直接看包裹里面的书不就行了吗？” 好问题！在某些情况下，你确实可以只关心数据本身。但是，元数据在以下场景中非常有用：

• 框架和库: 许多框架（比如 Angular, NestJS）使用元数据来实现依赖注入、路由、验证等功能。
• 类型检查: 可以用来增强类型信息，尤其是在 JavaScript 这种动态类型的语言中。
• AOP（面向切面编程）: 元数据可以用来定义切面，在方法执行前后插入额外的逻辑。
• 代码生成: 可以根据元数据自动生成代码。
• 文档生成: 可以从元数据中提取信息，自动生成文档。

总而言之，元数据让你在运行时能够获取关于代码结构的更多信息，从而实现更灵活、更强大的编程模式。

Reflect.metadata：元数据的魔法棒

Reflect.metadata 是一个 JavaScript 提案，旨在为 JavaScript 添加一种标准的方式来定义和访问元数据。 虽然这个提案目前仍处于Stage 2 阶段，尚未正式纳入 ECMAScript 标准，但许多 JavaScript 运行时和转译器（如 TypeScript）已经支持它。

这个提案的核心是 Reflect 对象上的几个方法：

• Reflect.defineMetadata(metadataKey, metadataValue, target)：在 target 上定义元数据。
• Reflect.getMetadata(metadataKey, target)：获取 target 上的元数据。
• Reflect.hasMetadata(metadataKey, target)：检查 target 上是否存在元数据。
• Reflect.deleteMetadata(metadataKey, target)：删除 target 上的元数据。
• Reflect.getMetadataKeys(target)：获取 target 上所有元数据的键。
• Reflect.getOwnMetadata(metadataKey, target)：获取 target 上直接定义的元数据（不包括原型链上的）。
• Reflect.getOwnMetadataKeys(target)：获取 target 上直接定义的所有元数据的键（不包括原型链上的）。

其中，target 可以是：

• 一个类（构造函数）
• 一个类的原型对象
• 一个类的方法
• 一个类的属性

metadataKey 是元数据的键，可以是任何值（通常是字符串或 Symbol）。 metadataValue 是元数据的值，可以是任何值。

让我们用代码来施展魔法

首先，我们需要确保我们的环境支持 Reflect.metadata。 如果你使用 TypeScript，你需要启用 emitDecoratorMetadata 选项。 如果你直接使用 JavaScript，你可能需要引入一个 polyfill，比如 reflect-metadata。

npm install reflect-metadata --save

然后在你的代码中引入它：

import 'reflect-metadata';

现在，我们就可以开始使用 Reflect.metadata 了。

例子 1：为类添加元数据

import 'reflect-metadata';

const MyClassMetadataKey = Symbol('MyClassMetadata');

@Reflect.metadata(MyClassMetadataKey, 'This is my class metadata!')
class MyClass {
  constructor() {
    console.log('MyClass constructor');
  }
}

const metadata = Reflect.getMetadata(MyClassMetadataKey, MyClass);
console.log(metadata); // 输出：This is my class metadata!

在这个例子中，我们使用 @Reflect.metadata 装饰器（decorator）为 MyClass 添加了元数据。 装饰器是一种特殊的语法，用于在运行时修改类、方法或属性的行为。 实际上，@Reflect.metadata 只是一个语法糖，它背后调用了 Reflect.defineMetadata 方法。

等价的 JavaScript 代码 (不使用装饰器):

import 'reflect-metadata';

const MyClassMetadataKey = Symbol('MyClassMetadata');

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

Reflect.defineMetadata(MyClassMetadataKey, 'This is my class metadata!', MyClass);

const metadata = Reflect.getMetadata(MyClassMetadataKey, MyClass);
console.log(metadata); // 输出：This is my class metadata!

例子 2：为属性添加元数据

import 'reflect-metadata';

const MyPropertyMetadataKey = Symbol('MyPropertyMetadata');

class MyClass {
  @Reflect.metadata(MyPropertyMetadataKey, 'This is my property metadata!')
  myProperty: string;

  constructor() {
    this.myProperty = 'Hello';
  }
}

const metadata = Reflect.getMetadata(MyPropertyMetadataKey, MyClass.prototype, 'myProperty');
console.log(metadata); // 输出：This is my property metadata!

请注意，当我们为属性添加元数据时，我们需要将 target 设置为 MyClass.prototype，并将属性名作为第三个参数传递给 Reflect.getMetadata。

例子 3：为方法添加元数据

import 'reflect-metadata';

const MyMethodMetadataKey = Symbol('MyMethodMetadata');

class MyClass {
  @Reflect.metadata(MyMethodMetadataKey, 'This is my method metadata!')
  myMethod() {
    console.log('My method');
  }
}

const metadata = Reflect.getMetadata(MyMethodMetadataKey, MyClass.prototype, 'myMethod');
console.log(metadata); // 输出：This is my method metadata!

和属性一样，我们需要将 target 设置为 MyClass.prototype，并将方法名作为第三个参数传递给 Reflect.getMetadata。

例子 4：使用 hasMetadata 和 deleteMetadata

import 'reflect-metadata';

const MyMetadataKey = Symbol('MyMetadata');

class MyClass {
  @Reflect.metadata(MyMetadataKey, 'My metadata')
  myProperty: string;
}

console.log(Reflect.hasMetadata(MyMetadataKey, MyClass.prototype, 'myProperty')); // 输出：true

Reflect.deleteMetadata(MyMetadataKey, MyClass.prototype, 'myProperty');

console.log(Reflect.hasMetadata(MyMetadataKey, MyClass.prototype, 'myProperty')); // 输出：false

例子 5：使用 getMetadataKeys 和 getOwnMetadataKeys

import 'reflect-metadata';

const MetadataKey1 = Symbol('Metadata1');
const MetadataKey2 = Symbol('Metadata2');

class BaseClass {
  @Reflect.metadata(MetadataKey1, 'Base metadata')
  baseProperty: string;
}

class MyClass extends BaseClass {
  @Reflect.metadata(MetadataKey2, 'My metadata')
  myProperty: string;
}

console.log(Reflect.getMetadataKeys(MyClass.prototype, 'myProperty')); // 输出：[ Symbol(Metadata2), Symbol(Metadata1) ]
console.log(Reflect.getOwnMetadataKeys(MyClass.prototype, 'myProperty')); // 输出：[ Symbol(Metadata2) ]

getMetadataKeys 会返回包括原型链上的所有元数据的键，而 getOwnMetadataKeys 只会返回直接定义在 target 上的元数据的键。

元数据与装饰器：天生一对

正如我们所见，装饰器是使用 Reflect.metadata 的一种非常方便的方式。 装饰器提供了一种声明式的语法来添加元数据，使代码更易于阅读和维护。

让我们看一个更复杂的例子，演示如何使用装饰器和元数据来实现一个简单的验证器：

import 'reflect-metadata';

const requiredMetadataKey = Symbol('required');

function Required(target: any, propertyKey: string | symbol, parameterIndex: number) {
  let existingRequiredParameters: number[] = Reflect.getOwnMetadata(requiredMetadataKey, target, propertyKey) || [];
  existingRequiredParameters.push(parameterIndex);
  Reflect.defineMetadata(requiredMetadataKey, existingRequiredParameters, target, propertyKey);
}

function validate(target: any, propertyName: string, descriptor: TypedPropertyDescriptor<Function>) {
  let method = descriptor.value!;

  descriptor.value = function () {
    let requiredParameters: number[] = Reflect.getOwnMetadata(requiredMetadataKey, target, propertyName);
    if (requiredParameters) {
      for (let parameterIndex of requiredParameters) {
        if (arguments.length <= parameterIndex || arguments[parameterIndex] === null || arguments[parameterIndex] === undefined) {
          throw new Error(`Missing required argument at index ${parameterIndex}`);
        }
      }
    }

    return method.apply(this, arguments);
  };
}

class Greeter {
  greeting: string;

  constructor(message: string) {
    this.greeting = message;
  }

  @validate
  greet(@Required name: string) {
    return "Hello, " + name + ", " + this.greeting;
  }
}

const greeter = new Greeter("how are you?");

try {
  console.log(greeter.greet("John")); // 输出：Hello, John, how are you?
  console.log(greeter.greet(undefined)); // 抛出错误：Missing required argument at index 0
} catch (e) {
  console.error(e.message);
}

在这个例子中：

• @Required 装饰器用于标记方法的参数为必需的。它使用 Reflect.defineMetadata 将参数的索引存储在元数据中。
• @validate 装饰器用于验证方法参数。它使用 Reflect.getOwnMetadata 获取必需参数的索引，并在方法执行前检查这些参数是否已提供。

这个例子展示了如何使用元数据和装饰器来实现 AOP 的一种简单形式。

Reflect.metadata 的一些注意事项

• Reflect.metadata 提案仍然处于草案阶段，这意味着它的 API 可能会发生变化。
• 过度使用元数据可能会使代码难以理解和调试。请谨慎使用。
• 元数据会增加代码的体积，因为它需要在运行时存储额外的信息。

总结

Reflect.metadata 提供了一种强大的方式来为 JavaScript 代码添加元数据，从而实现更灵活、更强大的编程模式。 尽管它仍然是一个提案，但它已经在许多框架和库中得到广泛应用。 掌握 Reflect.metadata 可以帮助你更好地理解和使用这些框架和库，并编写更具表达力的代码。

表格总结

方法名	描述	参数	返回值
defineMetadata	在目标对象上定义元数据。	metadataKey: any, metadataValue: any, target: object, propertyKey?: string | symbol	void
getMetadata	获取目标对象上的元数据。	metadataKey: any, target: object, propertyKey?: string | symbol	any – 找到的元数据的值，如果没有找到则返回 undefined。
hasMetadata	检查目标对象上是否存在元数据。	metadataKey: any, target: object, propertyKey?: string | symbol	boolean – 如果目标对象上存在指定的元数据，则返回 true，否则返回 false。
deleteMetadata	删除目标对象上的元数据。	metadataKey: any, target: object, propertyKey?: string | symbol	boolean – 如果成功删除元数据，则返回 true，否则返回 false（例如，如果元数据不存在）。
getMetadataKeys	获取目标对象上的所有元数据键（包括原型链上的）。	target: object, propertyKey?: string | symbol	Array<any> – 包含目标对象及其原型链上所有元数据键的数组。如果目标对象上没有任何元数据，则返回一个空数组。
getOwnMetadata	获取目标对象上直接定义的元数据（不包括原型链上的）。	metadataKey: any, target: object, propertyKey?: string | symbol	any – 找到的元数据的值，如果没有找到则返回 undefined。只查找目标对象本身，不包括原型链。
getOwnMetadataKeys	获取目标对象上直接定义的所有元数据键（不包括原型链上的）。	target: object, propertyKey?: string | symbol	Array<any> – 包含目标对象上直接定义的所有元数据键的数组。只查找目标对象本身，不包括原型链。如果目标对象上没有任何元数据，则返回一个空数组。

希望今天的魔法课堂能让你对 Reflect.metadata 有更深入的了解。 记住，元数据是代码的标签，善用它们可以让你写出更强大、更灵活的代码！ 感谢大家的参与！