本文翻譯自 reflect-metadata

給 ECMAScript 的源數(shù)據響應式 API 的原型（prototype）

Detailed proposal (...)

背景

1.在定義一個 class 的時候睛琳，修飾器通過聲明語法就可以擴展 class 和它的成員（members）的功能陆淀；
2.Traceur 把注釋和 class 的靜態(tài)屬性聯(lián)系起來志笼；
3.類似 C#(.NET) 與 Java 等語言提供屬性（attributes）或注釋來添加源數(shù)據到類型上鸭轮，同時有一個響應式 API 用來讀取 源數(shù)據。

目的

1.許多應用場景（組合/依賴注入瓢喉，運行時類型斷言摹蘑，響應式/鏡像，測試）需求一個通用的給 class 添加額外的源數(shù)據的方式扰法；
2.許多工具和庫需要一個通用的方法推斷源數(shù)據蛹含；
3.產生源數(shù)據的修飾器需要能夠與多個修飾器組合；
4.源數(shù)據應該不僅僅通過對象獲取塞颁，還可以使用相應的捕捉器(traps)從代理獲绕窒洹；
5.定義產生源數(shù)據的修飾器不應該太難或者太復雜祠锣；
6.源數(shù)據應該與其他語言或者運行時的ECMAScript功能通用酷窥。

語法

聲明式定義一個源數(shù)據

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

命令式定義一個源數(shù)據

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

命令式 （introspection）一個源數(shù)據

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

語義

1.對象擁有一個新的 [[Metadata]] 內部屬性，包含一個 Map伴网，這個 Map 的 key 是屬性的 key 或者 undefined蓬推，值是 源數(shù)據的 key 以及相應的 value 組成的 Maps。
2.對象會擁有多個新的內部方法：[[DefineOwnMetadata]], [[GetOwnMetadata]], [[HasOwnMetadata]] 等等
3.這些內部方法可以別代理覆蓋來提供額外的捕捉器（traps）
4.這些內部方法默認調用一系列抽象方法來定義或者讀取源數(shù)據
5.響應式對象會暴露 MOP 操作符允許命令式訪問源數(shù)據
6.通過類聲明（C）定義的源數(shù)據會存在 C.[[Metadata]], key 是 undefined
7.通過類聲明的靜態(tài)成員（members）定義的源數(shù)據會存在 C.[[Metadata]], key 是屬性的 key
8.通過類聲明的實例成員定義的源數(shù)據會存在C.[[Metadata]]澡腾，key 是屬性的key

API

//在對象或屬性上定義源數(shù)據
Reflect.defineMetadata(metadataKey, metadataValue, target);
Reflect.defineMetadata(metadataKey, metadataValue, target, propertyKey);

// 檢查某個源數(shù)據的 key 是否存在某個對象或屬性上
let result = Reflect.hasMetadata(metadataKey, target);
let result = Reflect.hasMetadata(metadataKey, target, propertyKey);

// 檢查是否有自帶源數(shù)據 key 存在某個對象或屬性上
let result = Reflect.hasOwnMetadata(metadataKey, target);
let result = Reflect.hasOwnMetadata(metadataKey, target, propertyKey);

// 通過 key 在對象或屬性的原型鏈上獲取源數(shù)據的值
let result = Reflect.getMetadata(metadataKey, target);
let result = Reflect.getMetadata(metadataKey, target, propertyKey);

// 通過 自帶源數(shù)據 key 在對象或屬性的原型鏈上獲取源數(shù)據的值
let result = Reflect.getOwnMetadata(metadataKey, target);
let result = Reflect.getOwnMetadata(metadataKey, target, propertyKey);

// 獲取對象或屬性原型鏈上的所有源數(shù)據
let result = Reflect.getMetadataKeys(target);
let result = Reflect.getMetadataKeys(target, propertyKey);

// 獲取對象或屬性上所有自帶的源數(shù)據 keys
let result = Reflect.getOwnMetadataKeys(target);
let result = Reflect.getOwnMetadataKeys(target, propertyKey);

// 在對象或屬性上刪除源數(shù)據
let result = Reflect.deleteMetadata(metadataKey, target);
let result = Reflect.deleteMetadata(metadataKey, target, propertyKey);

//通過修飾器在構造函數(shù)上應用源數(shù)據
@Reflect.metadata(metadataKey, metadataValue)
class C {

  // 通過修飾器在方法或屬性上應用源數(shù)據
  @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 內部的方法參數(shù)是把源數(shù)據的 key 和 value 放在目標或者屬性 key 之前募逞。這會導致屬性 key 是惟一的可選參數(shù)。也讓方法更容易與函數(shù) bind 結合（馋评？放接？）。也會降低針對class和屬性的生成源數(shù)據的修飾器的整體代碼體積以及復雜度

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 項目里添加實驗性提供的源數(shù)據修飾器苟蹈，你必須在你的 tsconfig.json 文件中把 experimentalDecorators 設置為 true
為了在你的 Typescirpt 項目里添加實驗性提供的 auto-generated type(自動生成類型)源數(shù)據 ，你必須在你的 tsconfig.json 文件中把 emitDecoratorMetadata 設置為 true

請注意右核，自動生成類型的源數(shù)據在環(huán)形或者先前（forward）依賴的時候可能會有一些問題

問題

• 如果沒有維護原型鏈慧脱，為類構造函數(shù)編寫的糟糕的可變修飾符可能會導致元數(shù)據丟失。但是贺喝，不維護類構造函數(shù)的變體裝飾器中的原型鏈也會產生其他負面影響菱鸥。

  • 如果正在發(fā)生變化的裝飾器返回從目標繼承而來的類表達式，或者返回裝飾器的代理躏鱼，則可以緩解這種情況

• 對象或屬性的方法的源數(shù)據是通過屬性 key 附加上的氮采，如果想要通過方法的函數(shù)（function of method）獲取源數(shù)據是不行的。（比如從類上面“撕掉”方法）染苛。