Decorator

簡介

Decorator 提案經過了大幅修改，目前還沒有定案，不知道語法會不會再變。下面的內容完全依據以前的提案，已經有點過時了。等待定案以后，需要完全重寫。

裝飾器（Decorator）是一種與類（class）相關的語法，用來注釋或修改類和類方法。許多面向對象的語言都有這項功能，目前有一個提案將其引入了 ECMAScript。

裝飾器是一種函數，寫成@ + 函數名。它可以放在類和類方法的定義前面。

@frozen class Foo {
  @configurable(false)
  @enumerable(true)
  method() {}


  @throttle(500)
  expensiveMethod() {}
}

上面代碼一共使用了四個裝飾器，一個用在類本身，另外三個用在類方法。它們不僅增加了代碼的可讀性，清晰地表達了意圖，而且提供一種方便的手段，增加或修改類的功能。

1. 類的裝飾

裝飾器可以用來裝飾整個類。

@testable
class MyTestableClass {
  // ...
}


function testable(target) {
  target.isTestable = true;
}


MyTestableClass.isTestable // true

上面代碼中，@testable 就是一個裝飾器。它修改了 MyTestableClass 這個類的行為，為它加上了靜態(tài)屬性 isTestable 。testable 函數的參數target 是 MyTestableClass 類本身。

基本上，裝飾器的行為就是下面這樣。

@decorator
class A {}


// 等同于


class A {}
A = decorator(A) || A;

也就是說，裝飾器是一個對類進行處理的函數。裝飾器函數的第一個參數，就是所要裝飾的目標類。

function testable(target) {
  // ...
}

上面代碼中， testable 函數的參數 target ，就是會被裝飾的類。

如果覺得一個參數不夠用，可以在裝飾器外面再封裝一層函數。

function testable(isTestable) {
  return function(target) {
    target.isTestable = isTestable;
  }
}


@testable(true)
class MyTestableClass {}
MyTestableClass.isTestable // true


@testable(false)
class MyClass {}
MyClass.isTestable // false

上面代碼中，裝飾器 testable 可以接受參數，這就等于可以修改裝飾器的行為。

注意，裝飾器對類的行為的改變，是代碼編譯時發(fā)生的，而不是在運行時。這意味著，裝飾器能在編譯階段運行代碼。也就是說，裝飾器本質就是編譯時執(zhí)行的函數。

前面的例子是為類添加一個靜態(tài)屬性，如果想添加實例屬性，可以通過目標類的 prototype 對象操作。

function testable(target) {
  target.prototype.isTestable = true;
}


@testable
class MyTestableClass {}


let obj = new MyTestableClass();
obj.isTestable // true

上面代碼中，裝飾器函數 testable 是在目標類的 prototype 對象上添加屬性，因此就可以在實例上調用。

下面是另外一個例子。

// mixins.js
export function mixins(...list) {
  return function (target) {
    Object.assign(target.prototype, ...list)
  }
}


// main.js
import { mixins } from './mixins'


const Foo = {
  foo() { console.log('foo') }
};


@mixins(Foo)
class MyClass {}


let obj = new MyClass();
obj.foo() // 'foo'

上面代碼通過裝飾器 mixins ，把 Foo 對象的方法添加到了 MyClass 的實例上面?？梢杂?Object.assign()模擬這個功能。

const Foo = {
  foo() { console.log('foo') }
};


class MyClass {}


Object.assign(MyClass.prototype, Foo);


let obj = new MyClass();
obj.foo() // 'foo'

實際開發(fā)中，React 與 Redux 庫結合使用時，常常需要寫成下面這樣。

class MyReactComponent extends React.Component {}


export default connect(mapStateToProps, mapDispatchToProps)(MyReactComponent);

有了裝飾器，就可以改寫上面的代碼。

@connect(mapStateToProps, mapDispatchToProps)
export default class MyReactComponent extends React.Component {}

相對來說，后一種寫法看上去更容易理解。

2. 方法的裝飾

裝飾器不僅可以裝飾類，還可以裝飾類的屬性。

class Person {
  @readonly
  name() { return `${this.first} ${this.last}` }
}

上面代碼中，裝飾器 readonly用來裝飾“類”的 name 方法。

裝飾器函數readonly 一共可以接受三個參數。

function readonly(target, name, descriptor){
  // descriptor對象原來的值如下
  // {
  //   value: specifiedFunction,
  //   enumerable: false,
  //   configurable: true,
  //   writable: true
  // };
  descriptor.writable = false;
  return descriptor;
}


readonly(Person.prototype, 'name', descriptor);
// 類似于
Object.defineProperty(Person.prototype, 'name', descriptor);

裝飾器第一個參數是類的原型對象，上例是 Person.prototype ，裝飾器的本意是要“裝飾”類的實例，但是這個時候實例還沒生成，所以只能去裝飾原型（這不同于類的裝飾，那種情況時 target 參數指的是類本身）；第二個參數是所要裝飾的屬性名，第三個參數是該屬性的描述對象。

另外，上面代碼說明，裝飾器（readonly）會修改屬性的描述對象（descriptor），然后被修改的描述對象再用來定義屬性。

下面是另一個例子，修改屬性描述對象的 enumerable 屬性，使得該屬性不可遍歷。

class Person {
  @nonenumerable
  get kidCount() { return this.children.length; }
}


function nonenumerable(target, name, descriptor) {
  descriptor.enumerable = false;
  return descriptor;
}

下面的@log裝飾器，可以起到輸出日志的作用。

class Math {
  @log
  add(a, b) {
    return a + b;
  }
}


function log(target, name, descriptor) {
  var oldValue = descriptor.value;


  descriptor.value = function() {
    console.log( Calling ${name} with , arguments);
    return oldValue.apply(this, arguments);
  };


  return descriptor;
}


const math = new Math();


// passed parameters should get logged now
math.add(2, 4);

上面代碼中，@log 裝飾器的作用就是在執(zhí)行原始的操作之前，執(zhí)行一次console.log，從而達到輸出日志的目的。

裝飾器有注釋的作用。

@testable
class Person {
  @readonly
  @nonenumerable
  name() { return ${this.first} ${this.last} }
}

從上面代碼中，我們一眼就能看出， Person 類是可測試的，而 name 方法是只讀和不可枚舉的。

下面是使用 Decorator 寫法的組件，看上去一目了然。

@Component({
  tag: 'my-component',
  styleUrl: 'my-component.scss'
})
export class MyComponent {
  @Prop() first: string;
  @Prop() last: string;
  @State() isVisible: boolean = true;


  render() {
    return (
      <p>Hello, my name is {this.first} {this.last}</p>
    );
  }
}

如果同一個方法有多個裝飾器，會像剝洋蔥一樣，先從外到內進入，然后由內向外執(zhí)行。

function dec(id){
  console.log('evaluated', id);
  return (target, property, descriptor) => console.log('executed', id);
}


class Example {
    @dec(1)
    @dec(2)
    method(){}
}
// evaluated 1
// evaluated 2
// executed 2
// executed 1

上面代碼中，外層裝飾器@dec(1)先進入，但是內層裝飾器@dec(2)先執(zhí)行。

除了注釋，裝飾器還能用來類型檢查。所以，對于類來說，這項功能相當有用。從長期來看，它將是 JavaScript 代碼靜態(tài)分析的重要工具。

3. 為什么裝飾器不能用于函數？

裝飾器只能用于類和類的方法，不能用于函數，因為存在函數提升。

var counter = 0;


var add = function () {
  counter++;
};


@add
function foo() {
}

上面的代碼，意圖是執(zhí)行后 counter 等于 1，但是實際上結果是 counter 等于 0。因為函數提升，使得實際執(zhí)行的代碼是下面這樣。

@add
function foo() {
}


var counter;
var add;


counter = 0;


add = function () {
  counter++;
};

下面是另一個例子。

var readOnly = require("some-decorator");


@readOnly
function foo() {
}

上面代碼也有問題，因為實際執(zhí)行是下面這樣。

var readOnly;


@readOnly
function foo() {
}


readOnly = require("some-decorator");

總之，由于存在函數提升，使得裝飾器不能用于函數。類是不會提升的，所以就沒有這方面的問題。

另一方面，如果一定要裝飾函數，可以采用高階函數的形式直接執(zhí)行。

function doSomething(name) {
  console.log('Hello, ' + name);
}


function loggingDecorator(wrapped) {
  return function() {
    console.log('Starting');
    const result = wrapped.apply(this, arguments);
    console.log('Finished');
    return result;
  }
}


const wrapped = loggingDecorator(doSomething);

4. core-decorators.js

core-decorators.js是一個第三方模塊，提供了幾個常見的裝飾器，通過它可以更好地理解裝飾器。

（1）@autobind

autobind裝飾器使得方法中的 this對象，綁定原始對象。

import { autobind } from 'core-decorators';


class Person {
  @autobind
  getPerson() {
    return this;
  }
}


let person = new Person();
let getPerson = person.getPerson;


getPerson() === person;
// true

（2）@readonly

readonly 裝飾器使得屬性或方法不可寫。

import { readonly } from 'core-decorators';


class Meal {
  @readonly
  entree = 'steak';
}


var dinner = new Meal();
dinner.entree = 'salmon';
// Cannot assign to read only property 'entree' of [object Object]

（3）@override

override裝飾器檢查子類的方法，是否正確覆蓋了父類的同名方法，如果不正確會報錯。

import { override } from 'core-decorators';


class Parent {
  speak(first, second) {}
}


class Child extends Parent {
  @override
  speak() {}
  // SyntaxError: Child#speak() does not properly override Parent#speak(first, second)
}


// or


class Child extends Parent {
  @override
  speaks() {}
  // SyntaxError: No descriptor matching Child#speaks() was found on the prototype chain.
  //
  //   Did you mean "speak"?
}

（4）@deprecate (別名@deprecated)

deprecate或deprecated裝飾器在控制臺顯示一條警告，表示該方法將廢除。

import { deprecate } from 'core-decorators';


class Person {
  @deprecate
  facepalm() {}


  @deprecate('We stopped facepalming')
  facepalmHard() {}


  @deprecate('We stopped facepalming', { url: 'http://knowyourmeme.com/memes/facepalm' })
  facepalmHarder() {}
}


let person = new Person();


person.facepalm();
// DEPRECATION Person#facepalm: This function will be removed in future versions.


person.facepalmHard();
// DEPRECATION Person#facepalmHard: We stopped facepalming


person.facepalmHarder();
// DEPRECATION Person#facepalmHarder: We stopped facepalming
//
//     See http://knowyourmeme.com/memes/facepalm for more details.
//

（5）@suppressWarnings

suppressWarnings裝飾器抑制 deprecated裝飾器導致的 console.warn()調用。但是，異步代碼發(fā)出的調用除外。

import { suppressWarnings } from 'core-decorators';


class Person {
  @deprecated
  facepalm() {}


  @suppressWarnings
  facepalmWithoutWarning() {
    this.facepalm();
  }
}


let person = new Person();


person.facepalmWithoutWarning();
// no warning is logged

5. 使用裝飾器實現(xiàn)自動發(fā)布事件

我們可以使用裝飾器，使得對象的方法被調用時，自動發(fā)出一個事件。

const postal = require("postal/lib/postal.lodash");


export default function publish(topic, channel) {
  const channelName = channel || '/';
  const msgChannel = postal.channel(channelName);
  msgChannel.subscribe(topic, v => {
    console.log('頻道: ', channelName);
    console.log('事件: ', topic);
    console.log('數據: ', v);
  });


  return function(target, name, descriptor) {
    const fn = descriptor.value;


    descriptor.value = function() {
      let value = fn.apply(this, arguments);
      msgChannel.publish(topic, value);
    };
  };
}

上面代碼定義了一個名為publish的裝飾器，它通過改寫` descriptor.value`` ，使得原方法被調用時，會自動發(fā)出一個事件。它使用的事件“發(fā)布/訂閱”庫是Postal.js。

它的用法如下。

// index.js
import publish from './publish';


class FooComponent {
  @publish('foo.some.message', 'component')
  someMethod() {
    return { my: 'data' };
  }
  @publish('foo.some.other')
  anotherMethod() {
    // ...
  }
}


let foo = new FooComponent();


foo.someMethod();
foo.anotherMethod();

以后，只要調用 someMethod 或者 anotherMethod ，就會自動發(fā)出一個事件。

$ bash-node index.js
頻道:  component
事件:  foo.some.message
數據:  { my: 'data' }


頻道:  /
事件:  foo.some.other
數據:  undefined

6. Mixin

在裝飾器的基礎上，可以實現(xiàn) Mixin 模式。所謂 Mixin模式，就是對象繼承的一種替代方案，中文譯為“混入”（mix in），意為在一個對象之中混入另外一個對象的方法。

請看下面的例子。

const Foo = {
  foo() { console.log('foo') }
};


class MyClass {}


Object.assign(MyClass.prototype, Foo);


let obj = new MyClass();
obj.foo() // 'foo'

上面代碼之中，對象 Foo 有一個 foo 方法，通過 Object.assign 方法，可以將 foo 方法“混入” MyClass 類，導致 MyClass 的實例 obj 對象都具有 foo 方法。這就是“混入”模式的一個簡單實現(xiàn)。

下面，我們部署一個通用腳本 mixins.js ，將 Mixin 寫成一個裝飾器。

export function mixins(...list) {
  return function (target) {
    Object.assign(target.prototype, ...list);
  };
}

然后，就可以使用上面這個裝飾器，為類“混入”各種方法。

import { mixins } from './mixins';


const Foo = {
  foo() { console.log('foo') }
};


@mixins(Foo)
class MyClass {}


let obj = new MyClass();
obj.foo() // "foo"

通過 mixins 這個裝飾器，實現(xiàn)了在 MyClass 類上面“混入” Foo 對象的 foo 方法。

不過，上面的方法會改寫 MyClass 類的 prototype 對象，如果不喜歡這一點，也可以通過類的繼承實現(xiàn) Mixin。

class MyClass extends MyBaseClass {
  /* ... */
}

上面代碼中， MyClass 繼承了 MyBaseClass 。如果我們想在 MyClass 里面“混入”一個 foo 方法，一個辦法是在 MyClass 和 MyBaseClass 之間插入一個混入類，這個類具有 foo 方法，并且繼承了 MyBaseClass 的所有方法，然后 MyClass 再繼承這個類。

let MyMixin = (superclass) => class extends superclass {
  foo() {
    console.log('foo from MyMixin');
  }
};

上面代碼中， MyMixin 是一個混入類生成器，接受 superclass 作為參數，然后返回一個繼承 superclass 的子類，該子類包含一個 foo 方法。

接著，目標類再去繼承這個混入類，就達到了“混入” foo 方法的目的。

class MyClass extends MyMixin(MyBaseClass) {
  /* ... */
}


let c = new MyClass();
c.foo(); // "foo from MyMixin"

如果需要“混入”多個方法，就生成多個混入類。

class MyClass extends Mixin1(Mixin2(MyBaseClass)) {
  /* ... */
}

這種寫法的一個好處，是可以調用 super ，因此可以避免在“混入”過程中覆蓋父類的同名方法。

let Mixin1 = (superclass) => class extends superclass {
  foo() {
    console.log('foo from Mixin1');
    if (super.foo) super.foo();
  }
};


let Mixin2 = (superclass) => class extends superclass {
  foo() {
    console.log('foo from Mixin2');
    if (super.foo) super.foo();
  }
};


class S {
  foo() {
    console.log('foo from S');
  }
}


class C extends Mixin1(Mixin2(S)) {
  foo() {
    console.log('foo from C');
    super.foo();
  }
}

上面代碼中，每一次混入發(fā)生時，都調用了父類的 super.foo 方法，導致父類的同名方法沒有被覆蓋，行為被保留了下來。

new C().foo()
// foo from C
// foo from Mixin1
// foo from Mixin2
// foo from S

7. Trait

Trait也是一種裝飾器，效果與Mixin 類似，但是提供更多功能，比如防止同名方法的沖突、排除混入某些方法、為混入的方法起別名等等。

下面采用traits-decorator這個第三方模塊作為例子。這個模塊提供的 traits 裝飾器，不僅可以接受對象，還可以接受 ES6 類作為參數。

import { traits } from 'traits-decorator';


class TFoo {
  foo() { console.log('foo') }
}


const TBar = {
  bar() { console.log('bar') }
};


@traits(TFoo, TBar)
class MyClass { }


let obj = new MyClass();
obj.foo() // foo
obj.bar() // bar

上面代碼中，通過 traits 裝飾器，在 MyClass 類上面“混入”了 TFoo 類的 foo 方法和 TBar 對象的 bar 方法。

Trait 不允許“混入”同名方法。

import { traits } from 'traits-decorator';


class TFoo {
  foo() { console.log('foo') }
}


const TBar = {
  bar() { console.log('bar') },
  foo() { console.log('foo') }
};


@traits(TFoo, TBar)
class MyClass { }
// 報錯
// throw new Error('Method named: ' + methodName + ' is defined twice.');
//        ^
// Error: Method named: foo is defined twice.

上面代碼中， TFoo 和 TBar 都有 foo 方法，結果 traits 裝飾器報錯。

一種解決方法是排除 TBar 的 foo 方法。

import { traits, excludes } from 'traits-decorator';


class TFoo {
  foo() { console.log('foo') }
}


const TBar = {
  bar() { console.log('bar') },
  foo() { console.log('foo') }
};


@traits(TFoo, TBar::excludes('foo'))
class MyClass { }


let obj = new MyClass();
obj.foo() // foo
obj.bar() // bar

上面代碼使用綁定運算符（::）在 TBar 上排除 foo 方法，混入時就不會報錯了。

另一種方法是為 TBar 的 foo 方法起一個別名。

import { traits, alias } from 'traits-decorator';


class TFoo {
  foo() { console.log('foo') }
}


const TBar = {
  bar() { console.log('bar') },
  foo() { console.log('foo') }
};


@traits(TFoo, TBar::alias({foo: 'aliasFoo'}))
class MyClass { }


let obj = new MyClass();
obj.foo() // foo
obj.aliasFoo() // foo
obj.bar() // bar

上面代碼為 TBar 的 foo 方法起了別名 aliasFoo ，于是 MyClass 也可以混入 TBar 的 foo 方法了。

alias 和 excludes 方法，可以結合起來使用。

@traits(TExample::excludes('foo','bar')::alias({baz:'exampleBaz'}))
class MyClass {}

上面代碼排除了 TExample 的 foo 方法和 bar 方法，為 baz 方法起了別名 exampleBaz 。

as 方法則為上面的代碼提供了另一種寫法。

@traits(TExample::as({excludes:['foo', 'bar'], alias: {baz: 'exampleBaz'}}))
class MyClass {}