元数据反射 API

注意：现在装饰器和装饰器元数据都已在 TC39 中达到第 3 阶段，下面提出的 API 不再考虑标准化。然而，本包将继续支持使用 TypeScript 旧版 --experimentalDecorators 选项的项目，因为某些项目可能无法迁移到使用标准装饰器。

• 详细提案

安装

npm install reflect-metadata

使用方法

NodeJS/浏览器中的 ES 模块、TypeScript/Babel、打包工具

// - 修改全局 `Reflect` 对象（或在 ES5 运行时中定义一个）。
// - 支持 ESM 和 CommonJS。
// - 包含用于旧运行时的 `Map`、`Set` 和 `WeakMap` 内部 polyfills。
import "reflect-metadata";

// - 修改全局 `Reflect` 对象（或在 ES5 运行时中定义一个）。
// - 支持 ESM 和 CommonJS。
// - 需要运行时支持 `package.json` 中的 `"exports"`。
// - 不包含内部 polyfills。
import "reflect-metadata/lite";

CommonJS

// - 修改全局 `Reflect` 对象（或在 ES5 运行时中定义一个）。
// - 包含用于旧运行时的 `Map`、`Set` 和 `WeakMap` 内部 polyfills。
require("reflect-metadata");

// - 修改全局 `Reflect` 对象（或在 ES5 运行时中定义一个）。
// - 需要运行时支持 `package.json` 中的 `"exports"`。
// - 不包含内部 polyfills。
require("reflect-metadata/lite");

通过 <script> 在浏览器中使用

HTML

<!-- 修改全局 `Reflect` 对象（或在 ES5 运行时中定义一个）。 -->
<!-- 包含用于旧运行时的 `Map`、`Set` 和 `WeakMap` 内部 polyfills。 -->
<script src="path/to/reflect-metadata/Reflect.js"></script>

<!-- 修改全局 `Reflect` 对象（或在 ES5 运行时中定义一个）。 -->
<!-- 不包含内部 polyfills。 -->
<script src="path/to/reflect-metadata/ReflectLite.js"></script>

脚本

// - 使编辑器中的类型可用。
/// <reference path="path/to/reflect-metadata/standalone.d.ts" />

背景

• 装饰器增加了在定义类时通过声明性语法增强类及其成员的能力。
• Traceur 将注解附加到类的静态属性上。
• 像 C#（.NET）和 Java 这样的语言支持为类型添加元数据的属性或注解，并提供用于读取元数据的反射 API。

目标

• 许多用例（组合/依赖注入、运行时类型断言、反射/镜像、测试）希望能够以一致的方式为类添加额外的元数据。
• 各种工具和库需要一种一致的方法来处理元数据。
• 产生元数据的装饰器（即"注解"）需要与修改装饰器普遍可组合。
• 元数据不仅应该在对象上可用，还应该通过代理及相关陷阱可用。
• 定义新的产生元数据的装饰器对开发者来说不应该过于繁琐或复杂。
• 元数据应该与 ECMAScript 的其他语言和运行时特性保持一致。

语法

• 元数据的声明式定义：

class C {
  @Reflect.metadata(metadataKey, metadataValue)
  method() {
  }
}

• 元数据的命令式定义：

Reflect.defineMetadata(metadataKey, metadataValue, C.prototype, "method");

• 元数据的命令式内省：

let obj = new C();
let metadataValue = Reflect.getMetadata(metadataKey, obj, "method");

语义

• 对象有一个新的 [[Metadata]] 内部属性，它将包含一个 Map，其键是属性键（或 undefined），值是元数据键到元数据值的 Map。
• 对象将有一些新的内部方法用于 [[DefineOwnMetadata]]、[[GetOwnMetadata]]、[[HasOwnMetadata]] 等。
  • 这些内部方法可以被代理重写以支持额外的陷阱。
  • 这些内部方法默认将调用一组抽象操作来定义和读取元数据。
• Reflect 对象将暴露 MOP 操作，允许命令式访问元数据。
• 在类声明 C 上定义的元数据存储在 C.[[Metadata]] 中，键为 undefined。
• 在类声明 C 的静态成员上定义的元数据存储在 C.[[Metadata]] 中，键为属性键。
• 在类声明 C 的实例成员上定义的元数据存储在 C.prototype.[[Metadata]] 中，键为属性键。

API

// 在对象或属性上定义元数据
Reflect.defineMetadata(metadataKey, metadataValue, target);
Reflect.defineMetadata(metadataKey, metadataValue, target, propertyKey);

// 检查对象或属性的原型链上是否存在元数据键
let result = Reflect.hasMetadata(metadataKey, target);
let result = Reflect.hasMetadata(metadataKey, target, propertyKey);

// 检查对象或属性是否存在自身的元数据键
let result = Reflect.hasOwnMetadata(metadataKey, target);
let result = Reflect.hasOwnMetadata(metadataKey, target, propertyKey);
// 获取对象或属性原型链上的元数据键的元数据值
let result = Reflect.getMetadata(metadataKey, target);
let result = Reflect.getMetadata(metadataKey, target, propertyKey);

// 获取对象或属性自身的元数据键的元数据值
let result = Reflect.getOwnMetadata(metadataKey, target);
let result = Reflect.getOwnMetadata(metadataKey, target, propertyKey);

// 获取对象或属性原型链上的所有元数据键
let result = Reflect.getMetadataKeys(target);
let result = Reflect.getMetadataKeys(target, propertyKey);

// 获取对象或属性自身的所有元数据键
let result = Reflect.getOwnMetadataKeys(target);
let result = Reflect.getOwnMetadataKeys(target, propertyKey);

// 删除对象或属性的元数据
let result = Reflect.deleteMetadata(metadataKey, target);
let result = Reflect.deleteMetadata(metadataKey, target, propertyKey);

// 通过装饰器将元数据应用于构造函数
@Reflect.metadata(metadataKey, metadataValue)
class C {
  // 通过装饰器将元数据应用于方法（属性）
  @Reflect.metadata(metadataKey, metadataValue)
  method() {
  }
}

替代方案

• 使用属性而不是单独的API。
  • 显而易见的缺点是这可能会产生大量代码：

function ParamTypes(...types) {
  return (target, propertyKey) => {
    const symParamTypes = Symbol.for("design:paramtypes");
    if (propertyKey === undefined) {
      target[symParamTypes] = types;
    }
    else {
      const symProperties = Symbol.for("design:properties");
      let properties, property;
      if (Object.prototype.hasOwnProperty.call(target, symProperties)) {
        properties = target[symProperties];
      }
      else {
        properties = target[symProperties] = {};
      }
      if (Object.prototype.hasOwnProperty.call(properties, propertyKey)) {
        property = properties[propertyKey];
      }
      else {
        property = properties[propertyKey] = {};
      }
      property[symParamTypes] = types;
    }
  };
}

注意事项

• 虽然看起来可能有悖直觉，但Reflect上的方法将元数据键和元数据值的参数放在目标或属性键之前。这是因为属性键是参数列表中唯一的可选参数。这也使得这些方法更容易与Function#bind进行柯里化。这还有助于减少可以同时针对类或属性的元数据生成装饰器的整体占用空间和复杂性：

function ParamTypes(...types) {
  // 由于propertyKey实际上是可选的，所以在这里使用更容易
  return (target, propertyKey) => { Reflect.defineMetadata("design:paramtypes", types, target, propertyKey); }

  // 相比之下，将目标和键放在前面会有多个重载：
  //
  // return (target, propertyKey) => {
  //    if (propertyKey === undefined) {
  //      Reflect.defineMetadata(target, "design:paramtypes", types);
  //    }
  //    else {
  //      Reflect.defineMetadata(target, propertyKey, "design:paramtypes", types);
  //    }
  // }
  //
  // 或者为类和属性使用不同的方法：
  //
  // return (target, propertyKey) => {
  //    if (propertyKey === undefined) {
  //      Reflect.defineMetadata(target, "design:paramtypes", types);
  //    }
  //    else {
  //      Reflect.definePropertyMetadata(target, propertyKey, "design:paramtypes", types);
  //    }
  // }
}

• 要在TypeScript项目中启用对元数据装饰器的实验性支持，你必须在tsconfig.json文件中添加"experimentalDecorators": true。
• 要在TypeScript项目中启用对自动生成的类型元数据的实验性支持，你必须在tsconfig.json文件中添加"emitDecoratorMetadata": true。
  • 请注意，自动生成的类型元数据可能会在循环引用或前向引用类型时出现问题。

问题

• 对于类构造函数编写不当的可变装饰器可能会导致元数据丢失，如果没有维护原型链的话。不过，在类构造函数的可变装饰器中不维护原型链也会产生其他负面影响。@rbuckton
  • 如果可变装饰器返回一个继承自目标的类表达式，或返回装饰器的代理，这个问题就可以得到缓解。@rbuckton
• 方法的元数据通过属性键附加到类（或原型）上。如果尝试读取方法函数的元数据（例如，从类中"分离"方法），那么这些元数据将不可用。@rbuckton