在一些優秀的開源框架，如 Angular、Nest.js、Midway 中會看到一種常見的寫法 @符號 + 方法名，做為一個只有 JavaScript 經驗的開發者第一次看到這種寫法還是感覺挺新奇的。
一個 @符號開頭 + 方法名，這種寫法正是 JavaScript 中的裝飾器 Decorators，它附加在我們定義的類、類方法、類字段、類訪問器、類自動訪問器上，在不改變原對象基礎上，為我們的程序增強一些功能，例如邏輯復用、代碼解耦。
如下所示 @executionTime 是我們實現的裝飾器函數，它會記錄被修飾方法的執行耗時，下文中我們會進行詳細的介紹。
class Person {
@executionTime
run() {}
}通過本文你將學到如下內容：
裝飾器動態
關于 JavaScript 裝飾器，已經提案很多年了，盡管提案還未進入最后階段，得益于 TypeScript 和 babel，我們可以在一些框架中提前使用到該技術。 先了解下裝飾器的最新動態，及在 TypeScript、babel 中的支持程度。
一個好消息是 2022-03 JavaScript 裝飾器提案終于進入到 stage 3 了，這已經是到了候選階段了，該階段會接收使用者的反饋并對提案完善，離最終的 stage 4 最近的一個階段了。查看進入到 TC39 提案的一些語法，參考這里閱讀更多 ECMAScript proposals。
一個提案進入到 stage 3 之后，TypeScript 就會去實現它。裝飾器是一個特殊的存在，目前 TypeScript 中的裝飾器實現還是基于第一版裝飾器的提案（這在早期對 TypeScript 也是一個賣點了），和現在 stage 3 中的提案存在很大的差別。
做為用戶可能會擔心，會不會出現不兼容的情況？兼容肯定是要的，舊版也不會立馬廢棄，現在是通過 --experimentalDecorators?、--emitDecoratorMetadata 兩個配置開啟裝飾器，stage 3 的提案離最終已經很近了，要么默認開啟，要么在增加一個新的配置開啟，對使用者來說也許不會有太大的差異，對于庫的開發者 目前 TS 裝飾器和 JS 最新的裝飾器提案實現已經不是一回事了，有很多問題需要考慮。
在可預見的未來，TypeScript 下個版本 5.0 大概率會實現新版裝飾器，參考 TypeScript 接下來的 5.0 版本迭代計劃，里面提到了 “實現更新后的 JavaScript 裝飾器提案”。
- TypeScript 5.0 Iteration Plan #51362
- Implement the updated JS decorators proposal #48885
babel 也一直在跟進 JavaScript 裝飾器提案，最新的 stage 3 版本也已實現，算是支持的比較好的了，通過 @babel/plugin-proposal-decorators 插件提供支持，裝飾器不同階段的提案 babel 都有實現，如下所示：
- 2022-03：在 2022 年 3 月的 TC39 會議上就 Stage 3 達成共識的提案版本。閱讀更多相關信息tc39/proposal-decorators@8ca65c046d。
- 2021-12：2021 年 12 月提交給 TC39 的提案版本。閱讀更多相關信息 tc39/proposal-decorators@d6c056fa06。
- 2018-09：最初提升到第 2 階段的提案版本，于 2018 年 9 月提交給 TC39。閱讀更多相關信息tc39/proposal-decorators@7fa580b40f。
- legacy：最初的第 1 階段提案，閱讀更多相關信息 wycats/javascript-decorators@e1bf8d41bf。
下文用到的所有的代碼會用 babel 編譯，接下來讓我們先搭建一個支持裝飾器的運行環境。
搭建裝飾器運行環境
babel 7.19.0 版本已支持 stage 3 裝飾器，安裝的 babel 大于此即可。
創建一個項目 decorators-demo
$ mkdir decorators-demo
$ cd decorators-demo
$ npm init
安裝 babel 依賴
npm i @babel/core @babel/cli @babel/preset-env @babel/plugin-proposal-decorators -D
創建一個名為 .babelrc 的新文件配置 babel
{
"presets": [
[
"@babel/preset-env",
{
"targets": {
"node": "current"
}
}
]
],
"plugins": [
["@babel/plugin-proposal-decorators", { "version": "2022-03" }] // 這個地方要配置，因為當前默認的版本不是最新的
]
}編輯 package.json scripts 命令
"scripts": {
"build": "babel index.js -d dist",
"start": "npm run build && node dist/index.js"
}類裝飾器
類裝飾器修飾的是定義的類本身，我們可以為它添加屬性、方法。類裝飾器類型簽名如下所示，第一個參數 value 就是被修飾的類。
類型簽名如下所示：
type ClassDecorator = (value: Function, context: {
kind: "class";
name: string | undefined;
addInitializer(initializer: () void): void;
}) => Function | void;為類擴展一個新方法
例如，再不改變原始代碼的情況下，借助外部組件使用類裝飾器為 Person 類擴展一個方法 run。
function addRunMethod(value, { kind, name }) {
if (kind === "class") {
return class extends value {
constructor(...args) {
super(...args);
}
run() {
console.log(`Add a run method for ${this.name}`);
}
}
}
}
@addRunMethod
class Person {
constructor(name) {
this.name = name
}
}
const p1 = new Person('Tom')
p1.run()
const p2 = new Person('Jack')
p2.run()
以上我們是通過繼承被修飾的類并返回一個新的子類方式來擴展一個新方法。我們定義的類裝飾器函數 addRunMethod 第一個參數既然是被修飾的類本身，因此我們還可以通過原型方式來擴展一個新的方法或屬性。
function addRunMethod(value, { kind }) {
if (kind === "class") {
value.prototype.run = function () {
console.log(`Add a run method for ${this.name}`);
}
}
}類方法裝飾器
類方法裝飾器接收一個被修飾的方法做為第一個參數，并可以選擇返回一個新方法替換原始的方法。類型簽名如下所示：
type ClassMethodDecorator = (value: Function, context: {
kind: "method";
name: string | symbol;
access: { get(): unknown };
static: boolean;
private: boolean;
addInitializer(initializer: () => void): void;
}) => Function | void;下面從一個記錄方法執行耗時的例子，做個不用裝飾器與用裝飾器的前后效果對比。日常開發工作中我們可能會有類似的需求：“記錄一個方法的執行時間，便于后續做些性能優化”。
示例：方法的計算耗時實現
下面定義了一個 Person 類，有一個 run（跑步） 方法，如果已經吃過飯了，他就有更多的力氣，跑的就會快些，否則就會跑的慢些。sleep 方法是為了輔助做些延遲測試。
const sleep = ms new Promise(resolve setTimeout(() resolve(1), ms));
class Person {
async run(isEat) {
const start = Date.now();
if (isEat) {
await sleep(1000 * 1);
console.log(`execution time: ${Date.now() - start}`);
return `I can run fast.`;
}
await sleep(1000 * 5);
console.log(`execution time: ${Date.now() - start}`);
return `I can't run any faster.`;
}
}
const p = new Person();
console.log(await p.run(true))
上面代碼暴露出兩個問題：
- 代碼耦合：計算方法執行耗時邏輯與業務代碼耦合，如果測試沒問題之后，想要移除這部分計算執行耗時的代碼邏輯，是不是就很難？
- 重復性代碼：一個方法內，代碼 7 行、12 行，計算最后耗時部分是完全重復的邏輯，如果還有一個別的方法是不是也要在寫一遍？
示例：使用裝飾器計算耗時
接下來使用類方法裝飾器改寫以上示例，類方法裝飾器第一個參數為被裝飾的函數，可以返回一個新函數來代替被裝飾的方法， 類型簽名如下所示：
type ClassMethodDecorator = (value: Function, context: {
kind: "method";
name: string | symbol;
access: { get(): unknown };
static: boolean;
private: boolean;
addInitializer(initializer: () void): void;
}) => Function | void;以下聲明一個 @executionTime? 裝飾器函數，該函數包裝原始函數，并在調用前后記錄函數執行耗時。
現在的代碼邏輯看起來是不是清晰了很多？通過裝飾器函數擴展了原有的功能，但并沒有修改原始函數內容，如果哪天想去掉計算函數執行耗時這段邏輯，也容易的多了。
const sleep = ms new Promise(resolve setTimeout(() resolve(1), ms));
function executionTime(value, context) {
const { kind, name } = context;
if (kind === 'method') {
return async function (...args) { // 返回一個新方法，代替被裝飾的方法
const start = Date.now();
const result = await value.apply(this, args);
console.log(`CALL method(${name}) execution time: ${Date.now() - start}`);
return result;
};
}
}
class Person {
@executionTime
async run(isEat) {
if (isEat) {
await sleep(1000 * 1); // 1 minute
return `I can run fast.`;
}
await sleep(1000 * 5); // 5 minute
return `I can't run any faster.`;
}
}
const p = new Person();
console.log(await p.run(true))
注意，類的構造函數不支持裝飾器，盡管構造函數看起來像方法，但實際上不是方法。
示例：實現 @bind 解決 this 問題
下面代碼直接執行 p.run() 是沒問題的，但是將 p.run 提取為一個方法再執行，此時函數內的 this 執行就發生變化了，會被指向為 undefined，單獨運行 run() 方法后就會出現 TypeError: Cannot read properties of undefined (reading '#name') 錯誤。
class Person {
#name
constructor(name) {
this.#name = name;
}
async run() {
console.log(`My name is ${this.#name}`);
}
}
const p = new Person('Tom');
const run = p.run;
run()裝飾器上下文對象上提供了一個 [添加初始化邏輯 addInitializer()](https://github.com/tc39/proposal-decorators#adding-initialization-logic-with-addinitializer) 方法，可以調用此方法將初始化函數與類或類元素相關聯，該方法在類實例化時會觸發，允許用戶在初始化時添加一些額外的邏輯。
例如，在這里我們可以聲明一個 @bind? 裝飾器在 addInitializer() 方法觸發時將類方法綁定到類實例，解決 this 綁定問題。
function bind(value, context) {
const { kind, name, addInitializer } = context;
if (kind === 'method') {
addInitializer(function () {
this[name] = value.bind(this);
});
}
}
class Person {
...
@bind
async run() {
console.log(`My name is ${this.#name}`);
}
}
示例：實現 @deprecated 提醒廢棄 API
對于某些在今后版本會被移除的 API，可以通過定義一個 @deprecated 的裝飾器，用于 API 將要廢棄的消息提醒。
const DEFAULT_MSG = 'This function will be removed in future versions.';
function deprecated(value, context) {
const { kind, name } = context;
if (kind === 'method') {
return function (...args) {
console.warn(`DEPRECATION ${name}: ${DEFAULT_MSG}`);
const result = value.apply(this, args);
return result;
};
}
}
class Person {
@deprecated
hello() {
console.log(`Hello world!`);
}
}
const p = new Person()
p.hello()
類訪問器裝飾器
類訪問器裝飾器與類方法裝飾器相似，區別地方在于上下文 context 對象的 kind 屬性為 getter、setter。
類型簽名如下所示：
type ClassGetterDecorator = (value: Function, context: {
kind: "getter" | "setter";
name: string | symbol;
access: { get(): unknown } | { set(value: unknown): void };
static: boolean;
private: boolean;
addInitializer(initializer: () => void): void;
}) => Function | void;示例：實現 @logged 裝飾器
下例，實現一個 @logged 裝飾器 追蹤函數被調用的前后記錄，細看是不是同上面我們自定義的類方法裝飾器 @executionTime 很相似。
function logged(value, context) {
const { kind, name } = context;
if (kind === 'method' || kind === 'getter' || kind === 'setter') {
return function (...args) { // 返回一個新方法，代替被裝飾的方法
console.log(`starting ${name} with arguments ${args.join(", ")}`);
const result = value.apply(this, args);
console.log(`ending ${name}`);
return result;
};
}
}
class Person {
#name
constructor(name) {
this.#name = name;
}
@logged
get name() {
return this.#name;
}
@logged
set name(name) {
this.#name = name;
}
}
const p = new Person('Tom')
p.name = 'Jack'
p.name
類自動訪問裝飾器
讓我們先拋開裝飾器的概念，了解下 accessor 是什么？
類新成員：自動訪問器
類自動訪問器（Auto-Accessors）是 ECMAScript 將要推出的一個新功能，目前 TC39 提案為 stage 1。通過 ??accessor?? 關鍵詞在類屬性前定義。
class Person {
accessor name = 'Tom';
}類自動訪問器相當于在類原型上定義了 getter、setter，大致等價于以下行為：
class Person {
#name = 'Tom';
get name() {
return this.#name;
}
set name(name) {
this.#name = name;
}
}自動訪問器裝飾器
自動訪問器裝飾器接收的第一個參數 value 包含了在類原型上定義的訪問器對象 get、set，第二參數 context 對象上的 kind 屬性為 accessor。
自動訪問器裝飾器允許攔截對屬性的訪問，在進行一些包裝之后，返回一個新的 **get**、**set**? 方法，還支持返回一個 **init** 函數，用于更改初始值
類型簽名如下所示：
type ClassAutoAccessorDecorator = (
value: {
get: () unknown;
set(value: unknown) => void;
},
context: {
kind: "accessor";
name: string | symbol;
access: { get(): unknown, set(value: unknown): void };
static: boolean;
private: boolean;
addInitializer(initializer: () => void): void;
}
) => {
get?: () => unknown;
set?: (value: unknown) => void;
init?: (initialValue: unknown) => unknown;
} | void;
示例：實現 @readOnly
實現一個 @readOnly 裝飾器，確保被裝飾的屬性在第一次初始化后可以變為只讀的，如果未被初始化不允許訪問該屬性，給一個錯誤提示。
const UNINITIALIZED = Symbol('UNINITIALIZED');
function readOnly(value, context) {
const { get, set } = value;
const { name, kind } = context;
if (kind === 'accessor') {
return {
init(initialValue) {
return initialValue || UNINITIALIZED;
},
get() {
const value = get.call(this);
if (value === UNINITIALIZED) {
throw new TypeError(
`Accessor ${name} hasn’t been initialized yet`
);
}
return value;
},
set(newValue) {
const oldValue = get.call(this);
if (oldValue !== UNINITIALIZED) {
throw new TypeError(
`Accessor ${name} can only be set once`
);
}
set.call(this, newValue);
},
};
}
}
class Person {
@readOnly
accessor name = 'Tom';
}
const p = new Person()
console.log(p.name);
// p.name = 'Jack' // TypeError: Accessor name can only be set once類字段裝飾器
類字段裝飾器接收到的第一個參數 value 為 undefined，我們不能更改字段的名稱。通過返回函數，我們可以接收字段的初始值并返回一個新的初始值。
類型簽名如下：
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;示例：將字段初始值翻倍
聲明一個 @multiples() 裝飾器，接收一個倍數，將字段初始值翻倍處理并返回。
function multiples(mutiple) {
return (value, { kind, name }) => {
if (kind === 'field') {
return initialValue initialValue * mutiple;
}
}
}
class Person {
@multiples(3)
count = 2;
}
const p = new Person();
console.log(p.count); // 6示例：依賴注入示例
Logger 是我們的基礎類，Person 類似于我們的業務類。以下代碼耦合的一點是 Person 與 Logger 產生了直接依賴，對于 Person 類只需要使用 Logger 實例，不需要把 Logger 實例化也放到 Person 類中。接下來我們要解決的是如何將兩個依賴模塊之間的初始化信息解耦。
class Logger {
info(...args) {
console.log(...args);
}
}
class Person {
logger = new Logger();
run() {
this.logger.info('Hi!', 'I am running.')
}
}
const p = new Person();
p.run();
依賴注入是將 “依賴” 注入給調用方，而不是讓調用方直接獲得依賴，在程序運行過程中由專門的組件負責 “依賴” 的實例化。
接下來，使用裝飾器和依賴注冊表實現依賴注入。
const assert = require('assert');
const { registry, inject } = createRegistry();
@registry.register('logger')
class Logger {
info(...args) {
console.log(new Date().toLocaleString(), ...args);
}
}
class Person {
@inject logger;
run() {
this.logger.info('Hi!', 'I am running.')
}
}
const p = new Person();
p.run();
assert.equal(p.logger, registry.getInstance('logger'));下面是核心方法 createRegistry() 的實現，參考了 JavaScript metaprogramming with the 2022-03 decorators API 的一個示例，下面主要用到了類裝飾器、類字段裝飾器。
function createRegistry() {
const classMap = new Map();
const instancesMap = new Map();
const registry = {
register(registerName) {
return (value, { kind }) => {
if (kind === 'class') {
classMap.set(registerName, value)
}
}
},
getInstance(name) {
if (instancesMap.has(name)) {
return instancesMap.get(name);
}
const TargetClass = classMap.get(name);
if (!TargetClass) {
throw new Error(`Unregistered dependencies with register name: ${name}`);
}
const instance = new TargetClass();
instancesMap.set(name, instance);
return instance;
},
}
return {
registry,
inject: (_value, {kind, name}) => {
if (kind === 'field') {
return () registry.getInstance(name);
}
}
};
}總結
裝飾器在未了解之前，給人一種神秘的感覺，了解之后會發現它的語法并沒有那么復雜。它的一個優點是在不改變原有代碼的基礎之上允許我們來擴展一些新功能。
裝飾器只適用于類，不支持函數。函數相對類來說，更容易做一些修飾，例如我們可以使用高階函數做一些包裝。
裝飾器可以應用于，類、類字段、類方法、類訪問器、類自動訪問器（這是類的一個新成員）。掌握了裝飾器的使用之后，再去看像 Nest.js、Angular 等這些框架時對于 @expression 這種語法，不會再陌生了。
在了解了裝飾器后，下一步讓我們在詳細了解下什么是 IoC（控制反轉）、DI（依賴注入）。
