(翻译)reflect-metadata

本文翻译自 reflect-metadata

给 ECMAScript 的源数据响应式 API 的原型（prototype）

Detailed proposal (...)

背景

1.在定义一个 class 的时候，修饰器通过声明语法就可以扩展 class 和它的成员（members）的功能；
2.Traceur 把注释和 class 的静态属性联系起来；
3.类似 C#(.NET) 与 Java 等语言提供属性（attributes）或注释来添加源数据到类型上，同时有一个响应式 API 用来读取 源数据。

目的

1.许多应用场景（组合/依赖注入，运行时类型断言，响应式/镜像，测试）需求一个通用的给 class 添加额外的源数据的方式；
2.许多工具和库需要一个通用的方法推断源数据；
3.产生源数据的修饰器需要能够与多个修饰器组合；
4.源数据应该不仅仅通过对象获取，还可以使用相应的捕捉器(traps)从代理获取；
5.定义产生源数据的修饰器不应该太难或者太复杂；
6.源数据应该与其他语言或者运行时的ECMAScript功能通用。

语法

声明式定义一个源数据

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

命令式定义一个源数据

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

命令式 （introspection）一个源数据

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

语义

1.对象拥有一个新的 [[Metadata]] 内部属性，包含一个 Map，这个 Map 的 key 是属性的 key 或者 undefined，值是 源数据的 key 以及相应的 value 组成的 Maps。
2.对象会拥有多个新的内部方法：[[DefineOwnMetadata]], [[GetOwnMetadata]], [[HasOwnMetadata]] 等等
3.这些内部方法可以别代理覆盖来提供额外的捕捉器（traps）
4.这些内部方法默认调用一系列抽象方法来定义或者读取源数据
5.响应式对象会暴露 MOP 操作符允许命令式访问源数据
6.通过类声明（C）定义的源数据会存在 C.[[Metadata]], key 是 undefined
7.通过类声明的静态成员（members）定义的源数据会存在 C.[[Metadata]], key 是属性的 key
8.通过类声明的实例成员定义的源数据会存在C.[[Metadata]]，key 是属性的key

API

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

// 检查某个源数据的 key 是否存在某个对象或属性上
let result = Reflect.hasMetadata(metadataKey, target);
let result = Reflect.hasMetadata(metadataKey, target, propertyKey);

// 检查是否有自带源数据 key 存在某个对象或属性上
let result = Reflect.hasOwnMetadata(metadataKey, target);
let result = Reflect.hasOwnMetadata(metadataKey, target, propertyKey);

// 通过 key 在对象或属性的原型链上获取源数据的值
let result = Reflect.getMetadata(metadataKey, target);
let result = Reflect.getMetadata(metadataKey, target, propertyKey);

// 通过 自带源数据 key 在对象或属性的原型链上获取源数据的值
let result = Reflect.getOwnMetadata(metadataKey, target);
let result = Reflect.getOwnMetadata(metadataKey, target, propertyKey);

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

// 获取对象或属性上所有自带的源数据 keys
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() {
  }
}

替代方案

1.使用属性而不是独立的 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 内部的方法参数是把源数据的 key 和 value 放在目标或者属性 key 之前。这会导致属性 key 是惟一的可选参数。也让方法更容易与函数 bind 结合（？？）。也会降低针对class和属性的生成源数据的修饰器的整体代码体积以及复杂度

function ParamTypes(...types) {
  // 因为 属性 key 是可选的，在这里使用很方便
  return (target, propertyKey) => { Reflect.defineMetadata("design:paramtypes", types, target, propertyKey); }

  // 对比，前面有多个负载（overloads）目标或 key
  //
  // return (target, propertyKey) => {
  //    if (propertyKey === undefined) {
  //      Reflect.defineMetadata(target, "design:paramtypes", types);
  //    }
  //    else {
  //      Reflect.defineMetadata(target, propertyKey, "design:paramtypes", types);
  //    }
  // }
  //
  // 对比，有针对 class 或属性的不同方法
  //
  // return (target, propertyKey) => {
  //    if (propertyKey === undefined) {
  //      Reflect.defineMetadata(target, "design:paramtypes", types);
  //    }
  //    else {
  //      Reflect.definePropertyMetadata(target, propertyKey, "design:paramtypes", types);
  //    }
  // }
}

为了在你的 Typescirpt 项目里添加实验性提供的源数据修饰器，你必须在你的 tsconfig.json 文件中把 experimentalDecorators 设置为 true
为了在你的 Typescirpt 项目里添加实验性提供的 auto-generated type(自动生成类型)源数据 ，你必须在你的 tsconfig.json 文件中把 emitDecoratorMetadata 设置为 true

请注意，自动生成类型的源数据在环形或者先前（forward）依赖的时候可能会有一些问题

问题

• 如果没有维护原型链，为类构造函数编写的糟糕的可变修饰符可能会导致元数据丢失。但是，不维护类构造函数的变体装饰器中的原型链也会产生其他负面影响。

  • 如果正在发生变化的装饰器返回从目标继承而来的类表达式，或者返回装饰器的代理，则可以缓解这种情况

• 对象或属性的方法的源数据是通过属性 key 附加上的，如果想要通过方法的函数（function of method）获取源数据是不行的。（比如从类上面“撕掉”方法）。