本文翻译自 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功能通用。
语法
声明式定义一个源数据
1 2 3 4 5 | class C { @Reflect.metadata(metadataKey, metadataValue) method() { } } |
命令式定义一个源数据
1 | Reflect.defineMetadata(metadataKey, metadataValue, C.prototype, "method"); |
命令式 (introspection)一个源数据
1 2 | let obj = new C(); let metadataValue = Reflect.getMetadata(metadataKey, obj, "method"); |
语义
1.对象拥有一个新的
2.对象会拥有多个新的内部方法:
3.这些内部方法可以别代理覆盖来提供额外的捕捉器(traps)
4.这些内部方法默认调用一系列抽象方法来定义或者读取源数据
5.响应式对象会暴露 MOP 操作符允许命令式访问源数据
6.通过类声明(C)定义的源数据会存在
7.通过类声明的静态成员(members)定义的源数据会存在
8.通过类声明的实例成员定义的源数据会存在
API
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 | //在对象或属性上定义源数据 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
明显的缺点就是需要更多的代码
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 | 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和属性的生成源数据的修饰器的整体代码体积以及复杂度
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 | 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 文件中把
为了在你的 Typescirpt 项目里添加实验性提供的
请注意,自动生成类型的源数据在环形或者先前(forward)依赖的时候可能会有一些问题
问题
-
如果没有维护原型链,为类构造函数编写的糟糕的可变修饰符可能会导致元数据丢失。但是,不维护类构造函数的变体装饰器中的原型链也会产生其他负面影响。
- 如果正在发生变化的装饰器返回从目标继承而来的类表达式,或者返回装饰器的代理,则可以缓解这种情况
-
对象或属性的方法的源数据是通过属性 key 附加上的,如果想要通过方法的函数(function of method)获取源数据是不行的。(比如从类上面“撕掉”方法)。