【用故事解读 MobX 源码（四）】装饰器 和 Enhancer

摘要：所以这是一篇插队的文章，用于去理解中的装饰器和概念。因此，该的作用就是根据入参返回具体的描述符。其次局部来看，装饰器具体应用表达式是，其函数签名和是一模一样。等装饰器语法，是和直接使用是等效等价的。

================前言===================

初衷：以系列故事的方式展现 MobX 源码逻辑，尽可能以易懂的方式讲解源码；

本系列文章：

《【用故事解读 MobX源码（一）】 autorun》

《【用故事解读 MobX源码（二）】 computed》

《【用故事解读 MobX源码（三）】 shouldCompute》

《【用故事解读 MobX 源码（四）】装饰器 和 Enhancer》

《【用故事解读 MobX 源码（五）】 Observable》

文章编排：每篇文章分成两大段，第一大段以简单的侦探系列故事的形式讲解（所涉及人物、场景都以 MobX 中的概念为原型创建），第二大段则是相对于的源码讲解。

本文基于 MobX 4 源码讲解

=======================================

按照步骤，这篇文章应该写 观察值（Observable）的，不过在撰写的过程中发现，如果不先搞明白装饰器和 Enhancer（对这个单词陌生的，先不要着急，继续往下看） ，直接去解释观察值（Observable）会很费劲。因为在 MobX 中是使用装饰器设计模式实现观察值的，所以说要先掌握装饰器，才能进一步去理解观察值。

所以这是一篇 “插队” 的文章，用于去理解 MobX 中的装饰器和 Enhancer 概念。

本文主要解决我个人在源码阅读中的疑惑：

在官方文档 如何(不)使用装饰器 中，为什么说开启 @observable、@computer 等装饰器语法，是和直接使用 decorate 是等效的？

在 MobX 源码中时常出现的 Enhancer 到底是个什么概念？它在 MobX 体系中发挥怎样的作用？它和装饰器又是怎么样的一层关系？

如果你也有这样的疑惑，不妨继续阅读本文，欢迎一起讨论。

至于 观察值（Observable），在本文中你只要掌握住 官方文档 observable 的用法就足够了，比如（示例摘自官方文档）：

const person = observable({
    firstName: "Clive Staples",
    lastName: "Lewis"
});
person.firstName = "C.S.";

const temperature = observable.box(20);
temperature.set(25);

对于 observable 方法的源码解析将在下一篇中详细展开，此篇文章不会做过多的讨论。

和其他语言（Python、Java）一样，装饰器语法是借助 @ 符号实现的，现在问题就归结到如何用 JS 去实现 @ 语法。

对于还不熟悉装饰器语法的读者，这里推荐文章 《ES7 Decorator 装饰者模式》，以钢铁侠为例，通过装备特殊的装备就能将普通人变成钢铁侠，简单概括起来就是：

装饰器设计模式的理念就和上面那样的朴素，在不改造 托尼·史塔克（Tony Stark） 本体的前提下，通过加装 盔甲、飞行器 的方式增强 Tony 的能力，从而“变成”钢铁侠。

有关装饰器使用的文章，还可以参考这两篇参考文章 探寻 ECMAScript 中的装饰器 Decorator、细说ES7 JavaScript Decorators

文章都比较早，当时写文章的作者都认为在新的 ES7 里会推出标准的 @ 语法，然而事后证明官方并没有这个意愿。我们知道目前的 ECMAScript 2015 标准，甚至到 ECMAScript 2018 标准官方都没有提供 @ 语法的支持，我们在其他文章中看到的 @ 语法都是通过 babel 插件来实现的。

上面提及的参考文章都是属于应用类型的，就是直接使用装饰器语法（即直接使用 @ 语法）来展示装饰器的实际应用，而对于如何实现 @ 语法并没有提及 —— 那就是如何用 Object.defineProperty 来实现 @ 语法。

道理大家都懂，那么到底如何才能自己动手去实现 @ 装饰器语法呢？

在 JS 中，我们借助 Object.defineProperty 方法实现装饰器设计模式，该方法签名如下：

Object.defineProperty(obj, prop, descriptor)

其中最核心的其实是 descriptor —— 属性描述符 。

属性描述符总共分两种：数据描述符（Data descriptor）和 访问器描述符（Accessor descriptor）。

描述符必须是两种形式之一，但不能同时是两者。

比如 数据描述符：

Object.getOwnPropertyDescriptor(user,"name");

// 输出
/**
{
  "value": "张三",
  "writable": true,
  "enumerable": true,
  "configurable": true
}
**/

还有 访问器描述符：

var anim = { 
  get age() { return 5; } 
};
Object.getOwnPropertyDescriptor(anim, "age");
// 输出
/**
{
   configurable: true,
   enumerable: true,
   get: /*the getter function*/,
   set: undefined
 }
**/

具体可参考 StackOverflow 上的问答 What is a descriptor? ；

接下来，我们一起来看一下 babel 中到底是如何实现 @ 语法的？

在理解属性描述符的基础上，我们就可以去看看 babel 对于装饰器 @ 语法的内部实现了。

就拿 MobX 官方的示例 来讲：

import { observable, computed, action } from "mobx";

class OrderLine {
    @observable price = 0;
    @observable amount = 1;

    @computed get total() {
        return this.price * this.amount;
    }
    
    @action.bound
    increment() {
        this.amount++ // "this" 永远都是正确的
    }
}

我们并不是真正想要运行上面那段代码，而是想看一下 babel 通过装饰器插件，把上面那段代码中的 @ 语法转换成什么样子了。

运行这段代码需要搭建 babel 环境，所以直接扔到浏览器运行会报错的。按照官方文档 如何(不)使用装饰器 中的提示，需要借助 babel-preset-mobx 插件，这是一个预设（preset，相当于 babel 插件集合），真正和装饰器有关的是插件是 babel-plugin-transform-decorators-legacy。

放到 babel 在线工具，粘贴现有的示例代码会报错，不过 babel 给出了友好的提示，因为使用到了装饰器语法，需要安装 babel-plugin-transform-decorators-legacy：

我们点击左下方的 Add Plugin 按钮，在弹出的搜索框里输入关键字 decorators-legacy，选择这个插件就可以：

选完插件之后，代码就会成功转译：

底下会提示 require is not defined 错误，这个错误并不影响你分析装饰器的语法，因为有 @ 符号部分都已经转换成 ES5 语法了，只是这个报错无法让这段示例代码运行起来。

这是因为 Babel 只是将最新的 ES6 语法“翻译”成各大浏览器支持比较好的 ES5 语法，但模块化写法（require语句）本身就不是 ECMAScript 的标准，而是产生了其他的模块化写法标准，例如 CommonJS，AMD,UMD。因此 Babel 转码模块化写法后在浏览器中还是无法运行，此时可以考虑放到 Webpack 这种自动化构建工具环境中，此时 Webpack 是支持模块化写法的

如果有强迫症的同学，非得想要这段代码运行起来，可以参考下述的 方法二。

官方提供了 mobx-react-boilerplate，clone 下来之后直接：

npm install
npm start

说明：package.json 中的 dependencies 字段比较陈旧了，可以自己手动更新到最新版本

打开控制台就可以看到 bundle.js 文件了：

这样，我们就可以直接在 index.js 中粘贴我们需要的代码，因为基于 Webpack 打包，所以示例代码是可以运行的。

上述两种方法因为都是使用同一个装饰器转换插件 babel-plugin-transform-decorators-legacy，所以装饰器语法部分转换后的代码是一样的。

比如针对 price 属性的装饰器语法：

@observable price = 0;

经过 babel 转译之后：

var _descriptor = _applyDecoratedDescriptor(
    _class.prototype,
    "price",
    [_mobx.observable],
    {
      enumerable: true,
      initializer: function initializer() {
        return 0;
      }
    }
  )

而对于 total 方法的装饰器语法：

@computed get total() {
    return this.price * this.amount;
}

经过 babel 转译之后则为：

_applyDecoratedDescriptor(
  _class.prototype,
  "total",
  [_mobx.computed],
  Object.getOwnPropertyDescriptor(_class.prototype, "total"),
  _class.prototype
);

可以看到关键是使用了 _applyDecoratedDescriptor 方法。接下来我们着重分析这个方法。

该函数签名为：

function _applyDecoratedDescriptor(
  target,
  property,
  decorators,
  descriptor,
  context
)

具体的用法，以 price 属性为例，我们可以获取对应的实参：

target：_class.prototype ，即 OrderLine.prototype

property：即字符串 "price"

decorators：在这里是 [_mobx.observable]（不同的修饰符装饰器是不一样的，比如使用 @computed 修饰的 total 方法，就是 [_mobx.computed]），是长度为 1 的数组，具体的 observable 方法将在下一篇文章详细讲，就是 createObservable

descriptor：即属性描述符，属性成员（比如 price）会有 initializer 属性，而方法成员（比如 total） 则不会有这个属性，用这个来区分这两种不同属性描述符。

{
  enumerable: true,
  initializer: function initializer() {
    return 0;
  }
}

context：就是运行上下文，一般来讲对数据属性的装饰则为 null，对方法属性则是 _class.prototype；

看完函数签名，我们继续看函数内容：

这几行代码没啥难度，就是我们熟悉的 属性描述符 相关的内容：

图中标注 ① ，表示返回的 desc 变量就是我们熟悉的 属性描述符。因此，该 _applyDecoratedDescriptor 的作用就是根据入参返回具体的描述符。

如果是属性成员（比如price），就将返回的描述符就可以传给 _initDefineProp （相当于 Object.defineProperty）应用到原来的属性中去了，从而起到了 装饰 作用。

图中标注 ② ，表示对于方法成员（比如 total）则直接应用 Object.defineProperty 方法（当是方法成员时，desc 是没有 initializer 属性的），同时令 desc = null，从后续的应用来看并不会和 _initDefineProp 方法搭配使用

对于图中标注 ③ ，我们具体看decorators 在其中发挥的作用，典型的函数式编程手法：

首先整体上来看，是一个循环语句。假如我们传入的 decorators 是 [a, b, c]，那么上面的代码相当于应用公式 a(b(c(property)))，也就是装饰器 c 先装饰属性 property，随后再叠加装饰器 b 的作用，最后叠加装饰器 a。以 price 属性为例，由于只有一个装饰器（@observable），所以只应用了 [_mobx.observable] 这一个装饰器。

其次局部来看，装饰器具体应用表达式是 decorator(target, property, desc) ，其函数签名和 Object.defineProperty 是一模一样。通过图中标注 ③ 我们可以理解，当我们写装饰器函数函数时，函数的定义入参必须是 (target, name, descriptor) 这样的，同时该函数必须要返回属性描述符。（可以停下来去翻翻看自己写装饰器函数的那些例子）

至此我们已经掌握了 babel 转换 @ 语法的精髓 —— 创建了 _applyDecoratedDescriptor 方法，从而依次应用你所定义的装饰器方法，而且也明白了自定义的装饰器方法的函数签名必须是 (target, name, descriptor) 的。

总结一下这个 babel 插件对于装饰器语法 @ 所做的事情：

通过 ast 分析，将 @ 语法转换成 _applyDecoratedDescriptor 方法的应用

_applyDecoratedDescriptor 方法就是一个循环应用装饰器的过程

那么接下来我们回到主题，mobx 如果不使用 babel 转译，那该如何实现类似于上述装饰器的语法呢？

很显然，MobX 不能实现（也没有必要）ast 分析将 @ 语法转换掉的功能，所以只能提供 循环应用装饰器 的这方面的功能。

为达到这个目的，MobX 4.x 版本相对 3.x 等以前版本多了 decorate API 方法。

官方文档 如何(不)使用装饰器 所言，使用装饰器 @ 语法等价于使用 decorate 方法，即改写成如下形式：

import { observable, computed, decorate, action } from "mobx";

class OrderLine {
    price = 0;
    amount = 1;

    get total() {
        return this.price * this.amount;
    }
}
decorate(OrderLine, {
    price: observable,
    amount: observable,
    total: computed,
    increment: action.bound
})

3.x 以前的版本因为没有 decorate 方法，所以是借助 extendObservable 方法实现的，具体见文档 在ES5、ES6和ES.next环境下使用 MobX

我们翻开 decorate 源码，该函数声明是：

decorate(thing, decorators)

thing：需要被装饰的原始对象；

decorators：装饰器配置对象，是一个 key/value 形式的对象， key 是属性名，value 就是具体的装饰器函数（比如 observable、computed 和 action.bound 这样具体的装饰器有效函数）

摘出核心语句：

可以看去的确就是一个 for 循环，然后依次应用 decorator，这恰好就是 babel 插件转换后 _applyDecoratedDescriptor 方法所做的事情，因此两者是等效的。

这样，就解答了本文开篇提出的第一个疑问。 @observable、@computer 等装饰器语法，是和直接使用 decorate 是等效等价的。

看到这里是不是觉得有点儿不可思议？嗯，事实上装饰器应用的过程就这么的简单。你也可以直接将这个 decorate API 方法直接提取到自己的项目中使用，给你的项目增加新的 feature。

解答完第一个问题，我们继续讲本文开头提出的另一个问题：MobX 中的 enhancer 是什么概念？

Enhancer 这个概念是 MobX 自己提出的一个概念，刚接触到的用户大多数会先蒙圈一会儿。

学习过 MobX 3.x 及以前版本的人可能会遇到 Modifier 这个概念，Enhancer 其实就是 Modifier。

Modifier 在 MobX 3 之前的版本里官方有专门的 文档 解说。不过到 MobX 4.x 之后官方就删除了这篇文档。好在这个概念是内部使用的，修改名字对外部调用者没有啥影响。

Enhancer 从字面上理解是 增强器，其作用就是给原有的对象 增加额外的功能 —— 这不就是装饰器的作用么？没错，它是辅助 MobX 中的 @observable 装饰器功能的。结合装饰器，会更加容易理解这个概念。

MobX 不是有很多种装饰器么，比如 @observable、@compute 和 @action，注意 Enhancer 只和 @observable 有关系，和 @compute 和 @action 是没啥关系的。这是因为 Enhancer 是为观察值（observable）服务的，和计算值（computedValue）和动作（Action）没关系。

@observable 装饰器中真正起作用的函数就是 Enhancer ，你可以将 Enhancer 理解成 @observable 装饰器有效的那部分。可以用 "药物胶囊