【Nest源码系列】装饰器元数据的奇妙联合(上)

一间房子里面放了一张床,这个房子满足了用来睡觉的基本需求,在这个基础上新增了沙发、红酒杯、电视机,那么就可以实现坐在沙发上摇着红酒看综艺节目的理想状态。此时沙发、红酒杯、电视机起到了装饰器的效果,在不影响房间可以用来睡觉的前提下扩展了更多的功能,实现松耦合和易扩展,这就是装饰器。

令人迷惑的装饰器参数

装饰器是贯穿Nest开发的重要部分,无论你编写模块、控制器、服务以及数据访问,都有对应的装饰器为你提供支持,比如这些:

通过调试,可以看到@UseGuards()源码是这样定义的,它接受三个参数:target、key、descriptor

还有@Controller()类装饰器和@Body()参数装饰器是这样的:

这样看好像没什么问题,我们知道目前浏览器不支持装饰器功能,还处于草案阶段,需要借助typescript的编译器或者babel进行编译才能执行,但你去翻一下ES6文档或ECMAScript提案,会发现stage-3的装饰器参数跟Nest源码中的并不相同,它们是这样的:

类装饰器:

typescript 复制代码
type ClassDecorator = (value: Function, context: {
  kind: "class";
  name: string | undefined;
  addInitializer(initializer: () => void): void;
}) => Function | void;

方法装饰器:

typescript 复制代码
type ClassMethodDecorator = (value: Function, context: {
  kind: "method";
  name: string | symbol;
  access: { get(): unknown };
  static: boolean;
  private: boolean;
  addInitializer(initializer: () => void): void;
}) => Function | void;

属性装饰器:

typescript 复制代码
type ClassFieldDecorator = (value: undefined, context: {
  kind: "field";
  name: string | symbol;
  access: { get(): unknown, set(value: unknown): void };
  static: boolean;
  private: boolean;
}) => (initialValue: unknown) => unknown | void;

它们只接受两个参数,value和context,其中value在不同的装饰器类型下表现不同,如在类中表示被修饰的类, 在方法中表示被修饰的方法 ;context是含有丰富信息的上下文对象

于是,有朋友可能产生了以下问题:

  • 为什么会这两种版本的装饰器?出现这个差异的原因是什么?
  • 虽然装饰器还在stage阶段,但事实上有很多的框架/库基于Babel或Tsc提供了装饰器的能力,它们各自是如何看齐ES规范的?目前各自的支持程度又到了哪个阶段?

要回答这些问题,要从装饰器发展史说起!

装饰器一路走来经历了什么

我们要知道,一个JavaScript特性正式进入规范是需要经历下面五个阶段,从 Stage 0(Strawman,初稿)开始,经 Stage 1(提案)、Stage 2(草案)、Stage 3(候选提案),最后到 Stage 4(Finished,过审提案)结束。

装饰器基于这个流程之上的时间顺序是这样的:

  • 2014-04-10:Yehuda Katz向TC39提出装饰器,提案进入了stage 0阶段
  • 2015-03-24:装饰器进入到stage 1阶段,当时是放在GitHub这个仓库的,后面统一迁移到了现在这个仓库
  • 2015-07-20:TypeScript 1.5 就开始支持了第一阶段的装饰器,通过--experimentalDecorators这个配置来开启。当时Angular和MobX也用上了这个TypeScript特性。
  • 2016-07-28:提案进入了stage 2阶段
  • 2022-03-28:提案进入了stage 3阶段,同时metadata也被单独出来作为一个题案,目前也进入了stage 3阶段
  • 2023-03-16:TypeScript5.0支持了第三阶段的装饰器!

由于babel在前端领域中占有重要的份额,我觉得有必要在这里扩展补充:

  • 2015-03-31: Babel 5.0.0 支持了stage 1的装饰器
  • 2015-11-29:Babel 6 中是用 Logan Smyth 写的扩展插件支持了 stage 1 的装饰器
  • 2018-08-27:Babel 7.0.0通过官方@babel/plugin-proposal-decorators支持第二阶段装饰器
  • 截止目前为止,官方插件目前支持以下版本
    • "legacy":第一阶段装饰器
    • "2018-09":第二阶段装饰器
    • "2021-12":原第二阶段装饰器的升级版
    • "2022-03":第三阶段装饰器
    • "2023-05":第三阶段装饰器升级版
    • "2023-01":第三阶段装饰器升级版

我们可以通过babel配置或者babel repl来切换这个版本

现在是不是对装饰器有更加清晰的认识了?我们再来看看Nest中tsconfig.json中的配置,默认开启了experimentalDecorators 配置,表示使用stage 1提案的装饰器

如果设置为false,那默认使用最新stage 3的装饰器,是有两个参数。另外,需要把emitDecoratorMetadata元数据配置也设为false,因为它是依赖experimentalDecorators的,这个会在后面讲IOC思想的时候再详细介绍。

以samples下的01-cats-app为例,把tsconfig.json这两个属性修改为这样:

重新npm run start:dev启动服务

编译报错提示在运行时接收到了2个参数,实际上@Controller() 预期接收1个,而@Post() 预期接收3个,明显是使用了stage 3最新提案的参数。

装饰器类型

从前面Nest源码我们可以发现,不同类型的装饰器接收的参数不一样,作用也不同,常用的装饰器有五中类型,分别是:

  • 类装饰器
  • 方法装饰器
  • 访问器装饰器
  • 属性装饰器
  • 参数装饰器

我们来过一下:

类装饰器

装饰器可以用来装饰整个类

typescript 复制代码
/**
 * 类装饰器
 */
const doc: ClassDecorator = (target: Function) => {
    console.log("---------------类装饰器-----------------");
    target.prototype.name = 'jmin'
    console.log(target);
    console.log("---------------类装饰器-----------------");
}

@doc
class App {
    constructor() {   
    }
}

const app: Record<string, any> = new App()
console.log('app name: ' + app.name);

上面代码中,@doc用来装饰App类,同时往原型链上添加一个属性为name,taget为修饰的类。

我们通过CodePen 来编译ES6代码,它是一个社区驱动的在线代码编辑器,支持编辑 HTML、CSS 和 JavaScript。它也支持 Babel,能够将 ES6 代码转换成 ES5 并进行实时预览。

由于本节案例中我们使用typescript编码,注意需要将语言类型切换为typescript。来看看效果:

方法的装饰

装饰器可以用来装饰类的方法

typescript 复制代码
/**
 * 方法装饰器
 */
const log: MethodDecorator = (target: Object, propertyKey: string | Symbol, descriptor: PropertyDescriptor) => {
  console.log("---------------方法装饰器-----------------");
  console.log(target);
  console.log(propertyKey);
  console.log(descriptor);
  console.log("---------------方法装饰器-----------------");
}

class User {
  @log
  getName() {
    return 'jmin';
  }
}

上面代码中,@log装饰器函数修饰User类方法getName,其中target为'装饰'类的原型,上例是User.prototype,由于这时候类还没有被实例化,只能去装饰原型对象,这是不同于类装饰器的,来看看运行效果:

由于User类原型还未挂载属性方法,所以是{}

访问器装饰器

访问器装饰器可以用来修饰类的setter和getter函数,跟类方法装饰器类似,唯一区别在于它们的描述器中有的key不同

方法装饰器的描述器的key为:

  • value
  • writable
  • enumerable
  • configurable

访问器装饰器的描述器的key为:

  • get
  • set
  • enumerable
  • configurable
typescript 复制代码
/**
 * 访问器装饰器
 */
const immutable: ParameterDecorator = (target: any, propertyKey: string | Symbol, descriptor: PropertyDescriptor) => {
    console.log('-------------访问器装饰器------------------');
    console.log(target);
    console.log(propertyKey);
    console.log(descriptor);
    console.log('-------------访问器装饰器------------------');   
}
class User {
    private _name = 'jmin'
    @immutable
    get name() {
      	return this._name;
    }
}

执行结果

属性的装饰

装饰器也可以用来修饰类属性

typescript 复制代码
/**
 * 属性装饰器
 */
const prop: PropertyDecorator = (target: Object, propertyKey: string | Symbol) => {
    console.log('------属性装饰器-------');
    
    console.log(target);
    console.log(propertyKey);
    
    console.log('------属性装饰器-------');

}

class User {
    @prop
    name: string = 'jmin'
}

上面代码中,@prop用于修饰Use类的name属性,此时target为装饰类的原型对象,propertyKey为修饰的属性

参数的装饰

还可以装饰类方法参数

typescript 复制代码
/**
 * 参数装饰器
 */

const param: ParameterDecorator = (target: Object, propertyKey: string | Symbol | undefined, index: number) => {
    console.log('-------------参数装饰器------------------');
    console.log(target);
    console.log(propertyKey);
    console.log(index);
    console.log('-------------参数装饰器------------------');   
}
class User {   
    getName(@param name: string) {
      	return name;
    }
}

上面代码中,@param用于装饰类方法getName的参数,其中target为装饰类的原型,propertyKey为装饰的类方法,index为装饰方法的参数索引位置,来看看效果:

但这些装饰器只有自带的几个参数信息,比如类装饰器中只有一个target参数并不够用怎么办呢?那就要用到工厂函数来增强装饰器能力了。比如这样:

typescript 复制代码
/**
 * 类装饰器
 */
const doc: ClassDecorator = (module) => {
    return (target: Function) => {
    	console.log("---------------类装饰器-----------------");
      target.prototype.module = module
    	console.log(target);
    	console.log("---------------类装饰器-----------------");
    }
}

@doc('user')
class App {
    constructor() {   
    }
}

const app: Record<string, any> = new App()
console.log('app module: ' + app.module);

上面代码通过装饰器工厂函数增强之后,@doc可以接受外部参数,使得App被实例化的时候有能力获取更多的信息来组织代码,到这里,你是不是已经明白了Nest中的装饰器是如何实现的?它在依赖注入中扮演着重要角色。

执行时机与顺序

我们重新把前面装饰类方法时执行结果拿过来

你也许会发现,即使类没有被实例化,但装饰器依旧会执行,这是因为装饰器是在解析阶段执行的。

对于属性/方法/访问器装饰器而言,它们的执行顺序取决于声明的先后顺序。

然而,同一方法中不同参数的装饰器的执行顺序是相反的, 最后一个参数的装饰器会最先被执行

less 复制代码
function func(key: string): any {
  console.log("evaluate: ", key);
  return function () {
    console.log("call: ", key);
  };
}

class C {
  method(
    @func("Parameter Foo") foo,
    @func("Parameter Bar") bar
  ) {}
}

执行结果为:

sql 复制代码
evaluate:  Parameter Foo
evaluate:  Parameter Bar
call:  Parameter Bar
call:  Parameter Foo

参数装饰器优先于方法装饰器执行。


less 复制代码
function func(key: string): any {
  console.log("evaluate: ", key);
  return function () {
    console.log("call: ", key);
  };
}

class C {
  @func("Method method")
  method(
    @func("Parameter Bar") bar
  ) {}
}

执行结果为:

sql 复制代码
evaluate: Method method
evaluate: Parameter Bar
call: Parameter Bar
call: Method method

了解完这几个概念后再来看看Nest中的装饰器就很好理解了,把前面令人迷惑的代码再贴过来。

现在你是不是知道了不同装饰器是有不同的工厂来处理的,接着获取到不同的元数据 通过Reflect.defineMetadata这个API存起来,等到需要的时候再拿出来使用。

小结

通过看Nest中装饰器的源码实现,发现参数个数跟最新提案的不一样,以这个契机我们顺藤摸瓜了解了规范的五个阶段,Babel通过官方@babel/plugin-proposal-decorators插件提供支持,TypeScript则通过experimentalDecorators实现了对规范的兼容和支持,我们可以通过里面的配置实现切换不同版本。

接着介绍5个常用的装饰器类型,在Nest中的装饰器无非也就这几种,它们都是通过装饰器工厂增强能力。

装饰器执行时机的先后顺序取决于声明的顺序,而参数装饰器是从最后一个开始往前执行,它们都是在解析阶段执行的。

下一节我们结合元数据来实现一个参数验证器。

相关推荐
类人_猿1 小时前
ASP.NET Web(.Net Framework) Http服务器搭建以及IIS站点发布
前端·iis·asp.net·.net·http站点服务器
组态软件4 小时前
web组态软件
前端·后端·物联网·编辑器·html
前端Hardy4 小时前
HTML&CSS:MacBook Air 3D 动画跃然屏上
前端·javascript·css·3d·html
loey_ln5 小时前
观察者模式和发布订阅模式
javascript·观察者模式·react.js
cnsxjean7 小时前
SpringBoot集成Minio实现上传凭证、分片上传、秒传和断点续传
java·前端·spring boot·分布式·后端·中间件·架构
ZL_5677 小时前
uniapp中使用uni-forms实现表单管理,验证表单
前端·javascript·uni-app
沉浮yu大海8 小时前
Vue.js 组件开发:构建可重用且高效的 UI 块
前端·vue.js·ui
代码欢乐豆8 小时前
软件工程第13章小测
服务器·前端·数据库·软件工程
sunly_8 小时前
Flutter:启动屏逻辑处理02:启动页
android·javascript·flutter
EasyNTS8 小时前
H5流媒体播放器EasyPlayer.js网页直播/点播播放器如果H.265视频在播放器上播放不流畅,可以考虑的解决方案
javascript·音视频·h.265