Decorator（裝飾器）是ECMAScript中一種與class相關的語法，用於給物件在執行期間動態的增加功能。Node.js還不支援Decorator，可以使用Babel進行轉換，也可以在TypeScript中使用Decorator。本示例則是基於TypeScript來介紹如何在node服務中使用Decorator。
## 一、	TypeScript相關
由於使用了 TypeScript ，需要安裝TypeScript相關的依賴，並在根目錄新增 tsconfig.json 配置檔案，這裡不再詳細說明。要想在 TypeScript 中使用Decorator 裝飾器，必須將 tsconfig.json 中 experimentalDecorators設定為true，如下所示：
### 	tsconfig.json

```
{
  "compilerOptions": {
    …
    // 是否啟用實驗性的ES裝飾器
    "experimentalDecorators": true
  }
}
```

## 二、	裝飾器介紹
### 1.	簡單示例
Decorator實際是一種語法糖，下面是一個簡單的用TypeScript編寫的裝飾器示例：

```

const Controller: ClassDecorator = (target: any) => {
    target.isController = true;
};

@Controller
class MyClass {

}

console.log(MyClass.isController); // 輸出結果：true
```

Controller是一個類裝飾器，在MyClass類宣告前以 @Controller 的形式使用裝飾器，新增裝飾器後MyClass. isController 的值為true。
編譯後的程式碼如下：

```
var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
    return c > 3 && r && Object.defineProperty(target, key, r), r;
};

const Controller = (target) => {
    target.isController = true;
};
let MyClass = class MyClass {
};
MyClass = __decorate([
    Controller
], MyClass);
```

### 2.	工廠方法
在使用裝飾器的時候有時候需要給裝飾器傳遞一些引數，這時可以使用裝飾器工廠方法，示例如下：

```
function controller ( label: string): ClassDecorator {
    return (target: any) => {
        target.isController = true;
        target.controllerLabel = label;
    };
}

@controller('My')
class MyClass {

}

console.log(MyClass.isController); // 輸出結果為： true
console.log(MyClass.controllerLabel); // 輸出結果為： "My"
```

controller 方法是裝飾器工廠方法，執行後返回一個類裝飾器，透過在MyClass類上方以 @controller('My') 格式新增裝飾器，新增後 MyClass.isController 的值為true，並且MyClass.controllerLabel 的值為 "My"。

### 3.	類裝飾器
類裝飾器的型別定義如下：

```
type ClassDecorator = <tfunction extends="" function="">(target: TFunction) => TFunction | void;
```

類裝飾器只有一個引數target，target為類的建構函式。
類裝飾器的返回值可以為空，也可以是一個新的建構函式。
下面是一個類裝飾器示例：

```
interface Mixinable {
    [funcName: string]: Function;
}
function mixin ( list: Mixinable[]): ClassDecorator {
    return (target: any) => {
        Object.assign(target.prototype, ...list)
    }
}

const mixin1 = {
    fun1 () {
        return 'fun1'
    }
};

const mixin2 = {
    fun2 () {
        return 'fun2'
    }
};

@mixin([ mixin1, mixin2 ])
class MyClass {

}

console.log(new MyClass().fun1()); // 輸出：fun1
console.log(new MyClass().fun2()); // 輸出：fun2
```

mixin是一個類裝飾器工廠，使用時以 @mixin() 格式新增到類宣告前，作用是將引數陣列中物件的方法新增到 MyClass 的原型物件上。

### 4.	屬性裝飾器
屬性裝飾器的型別定義如下：

```
type PropertyDecorator = (target: Object, propertyKey: string | symbol) => void;
```

屬性裝飾器有兩個引數 target 和 propertyKey。

- target：靜態屬性是類的建構函式，例項屬性是類的原型物件
- propertyKey：屬性名

下面是一個屬性裝飾器示例：

```
interface CheckRule {
    required: boolean;
}
interface MetaData {
    [key: string]: CheckRule;
}

const Required: PropertyDecorator = (target: any, key: string) => {
    target.__metadata = target.__metadata ? target.__metadata : {};
    target.__metadata[key] = { required: true };
};

class MyClass {
    @Required
    name: string;
    
    @Required
    type: string;
}
```

@Required 是一個屬性裝飾器，使用時新增到屬性宣告前，作用是在 target 的自定義屬性__metadata中新增對應屬性的必填規則。上例新增裝飾器後target.__metadata 的值為：{ name: { required: true }, type: { required: true } }。
透過讀取 __metadata 可以獲得設定的必填的屬性，從而對例項物件進行校驗，校驗相關的程式碼如下：

```
function validate(entity): boolean {
    // @ts-ignore
    const metadata: MetaData = entity.__metadata;
    if(metadata) {
        let i: number,
            key: string,
            rule: CheckRule;
        const keys = Object.keys(metadata);
        for (i = 0; i < keys.length; i++) {
            key = keys[i];
            rule = metadata[key];
            if (rule.required && (entity[key] === undefined || entity[key] === null || entity[key] === '')) {
                return false;
            }
        }
    }
    return true;
}

const entity: MyClass = new MyClass();
entity.name = 'name';
const result: boolean = validate(entity);
console.log(result); // 輸出結果：false
```

### 5.	方法裝飾器
方法裝飾器的型別定義如下：

```
type MethodDecorator = <t>(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<t>) => TypedPropertyDescriptor<t> | void;
```

方法裝飾器有3個引數 target 、 propertyKey 和 descriptor。

- target：靜態方法是類的建構函式，例項方法是類的原型物件
- propertyKey：方法名
- descriptor：屬性描述符
方法裝飾器的返回值可以為空，也可以是一個新的屬性描述符。
下面是一個方法裝飾器示例：

```
const Log: MethodDecorator = (target: any, key: string, descriptor: PropertyDescriptor) => {
    const className = target.constructor.name;
    const oldValue = descriptor.value;
    descriptor.value = function(...params) {
        console.log(`呼叫${className}.${key}()方法`);
        return oldValue.apply(this, params);
    };
};

class MyClass {
    private name: string;

constructor(name: string) {
        this.name = name;
    }

@Log
    getName (): string {
        return 'Tom';
    }
}

const entity = new MyClass('Tom');
const name = entity.getName();
// 輸出: 呼叫MyClass.getName()方法

```

@Log 是一個方法裝飾器，使用時新增到方法宣告前，用於自動輸出方法的呼叫日誌。方法裝飾器的第3個引數是屬性描述符，屬性描述符的value表示方法的執行函式，用一個新的函式替換了原來值，新的方法還會呼叫原方法，只是在呼叫原方法前輸出了一個日誌。

### 6.	訪問符裝飾器
訪問符裝飾器的使用與方法裝飾器一致，引數和返回值相同，只是訪問符裝飾器用在訪問符宣告之前。需要注意的是，TypeScript不允許同時裝飾一個成員的get和set訪問符。下面是一個訪問符裝飾器的示例：

```

const Enumerable: MethodDecorator = (target: any, key: string, descriptor: PropertyDescriptor) => {
    descriptor.enumerable = true;
};

class MyClass {
    createDate: Date;
    constructor() {
        this.createDate = new Date();
    }

@Enumerable
    get createTime () {
        return this.createDate.getTime();
    }
}

const entity = new MyClass();
for(let key in entity) {
    console.log(`entity.${key} =`, entity[key]);
}
/* 輸出：
entity.createDate = 2020-04-08T10:40:51.133Z
entity.createTime = 1586342451133
 */

```

MyClass 類中有一個屬性createDate 為Date型別， 另外增加一個有 get 宣告的createTime方法，就可以以 entity.createTime 方式獲得 createDate 的毫秒值。但是 createTime 預設是不可列舉的，透過在宣告前增加 @Enumerable 裝飾器可以使 createTime 成為可列舉的屬性。

### 7.	引數裝飾器
引數裝飾器的型別定義如下：

```
type ParameterDecorator = (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
```

引數裝飾器有3個引數 target 、 propertyKey 和 descriptor。

- target：靜態方法的引數是類的建構函式，例項方法的引數是類的原型物件
- propertyKey：引數所在方法的方法名
- parameterIndex：在方法引數列表中的索引值
在上面 @Log 方法裝飾器示例的基礎上，再利用引數裝飾器對新增日誌的功能進行擴充套件，增加引數資訊的日誌輸出，程式碼如下：

```
function logParam (paramName: string = ''): ParameterDecorator  {
    return (target: any, key: string, paramIndex: number) => {
        if (!target.__metadata) {
            target.__metadata = {};
        }
        if (!target.__metadata[key]) {
            target.__metadata[key] = [];
        }
        target.__metadata[key].push({
            paramName,
            paramIndex
        });
    }
}

const Log: MethodDecorator = (target: any, key: string, descriptor: PropertyDescriptor) => {
    const className = target.constructor.name;
    const oldValue = descriptor.value;
    descriptor.value = function(...params) {
        let paramInfo = '';
        if (target.__metadata && target.__metadata[key]) {
            target.__metadata[key].forEach(item => {
                paramInfo += `\n * 第${item.paramIndex}個引數${item.paramName}的值為: ${params[item.paramIndex]}`;
            })
        }
        console.log(`呼叫${className}.${key}()方法` + paramInfo);
        return oldValue.apply(this, params);
    };
};

class MyClass {
    private name: string;

constructor(name: string) {
        this.name = name;
    }

@Log
    getName (): string {
        return 'Tom';
    }

@Log
    setName(@logParam() name: string): void {
        this.name = name;
    }

@Log
    setNames( @logParam('firstName') firstName: string, @logParam('lastName') lastName: string): void {
        this.name = firstName + '' + lastName;
    }
}

const entity = new MyClass('Tom');
const name = entity.getName();
// 輸出：呼叫MyClass.getName()方法

entity.setName('Jone Brown');
/* 輸出：
呼叫MyClass.setNames()方法
 * 第0個引數的值為: Jone Brown
*/

entity.setNames('Jone', 'Brown');
/* 輸出：
呼叫MyClass.setNames()方法
 * 第1個引數lastName的值為: Brown
 * 第0個引數firstName的值為: Jone
*/
```

@logParam 是一個引數裝飾器，使用時新增到引數宣告前，用於輸出引數資訊日誌。

### 8.	執行順序
不同宣告上的裝飾器將按以下順序執行：

1.	例項成員的裝飾器：
引數裝飾器 > 方法裝飾器 > 訪問符裝飾器/屬性裝飾器
2.	靜態成員的裝飾器：
引數裝飾器 > 方法裝飾器 > 訪問符裝飾器/屬性裝飾器
3.	建構函式的引數裝飾器
4.	類裝飾器

如果同一個宣告有多個裝飾器，離宣告越近的裝飾器越早執行：

```
const A: ClassDecorator = (target) => {
    console.log('A');
};

const B: ClassDecorator = (target) => {
    console.log('B');
};

@A
@B
class MyClass {

}

/* 輸出結果：
B
A
*/
```

## 三、	Reflect Metadata
## 1.	安裝依賴
Reflect Metadata是的一個實驗性介面，可以透過裝飾器來給類新增一些自定義的資訊。這個介面目前還不是 ECMAScript  標準的一部分，需要安裝 reflect-metadata墊片才能使用。

```
npm install reflect-metadata --save
```

或者

```
yarn add reflect-metadata
```

另外，還需要在全域性的位置匯入此模組，例如：入口檔案。

```
import 'reflect-metadata';
```

### 2.	相關介面
Reflect Metadata 提供的介面如下：

```
// 定義後設資料
Reflect.defineMetadata(metadataKey, metadataValue, target);
Reflect.defineMetadata(metadataKey, metadataValue, target, propertyKey);

// 檢查指定關鍵字的後設資料是否存在，會遍歷繼承鏈
let result1 = Reflect.hasMetadata(metadataKey, target);
let result2 = Reflect.hasMetadata(metadataKey, target, propertyKey);

// 檢查指定關鍵字的後設資料是否存在，只判斷自己的，不會遍歷繼承鏈
let result3 = Reflect.hasOwnMetadata(metadataKey, target);
let result4 = Reflect.hasOwnMetadata(metadataKey, target, propertyKey);

// 獲取指定關鍵字的後設資料值，會遍歷繼承鏈
let result5 = Reflect.getMetadata(metadataKey, target);
let result6 = Reflect.getMetadata(metadataKey, target, propertyKey);

// 獲取指定關鍵字的後設資料值，只查詢自己的，不會遍歷繼承鏈
let result7 = Reflect.getOwnMetadata(metadataKey, target);
let result8 = Reflect.getOwnMetadata(metadataKey, target, propertyKey);

// 獲取後設資料的所有關鍵字，會遍歷繼承鏈
let result9 = Reflect.getMetadataKeys(target);
let result10 = Reflect.getMetadataKeys(target, propertyKey);

// 獲取後設資料的所有關鍵字，只獲取自己的，不會遍歷繼承鏈
let result11 = Reflect.getOwnMetadataKeys(target);
let result12 = Reflect.getOwnMetadataKeys(target, propertyKey);

// 刪除指定關鍵字的後設資料
let result13 = Reflect.deleteMetadata(metadataKey, target);
let result14 = Reflect.deleteMetadata(metadataKey, target, propertyKey);

// 裝飾器方式設定後設資料
@Reflect.metadata(metadataKey, metadataValue)
class C {
    @Reflect.metadata(metadataKey, metadataValue)
    method() {
    }
}
```

### 3.	design型別後設資料
要使用design型別後設資料需要在tsconfig.json中設定emitDecoratorMetadata為true，如下所示：

- tsconfig.json

```
{
  "compilerOptions": {
…
    // 是否啟用實驗性的ES裝飾器
    "experimentalDecorators": true

// 是否自動設定design型別後設資料（關鍵字有"design:type"、"design:paramtypes"、"design:returntype"）
    "emitDecoratorMetadata": true
  }
}
```

emitDecoratorMetadata 設為true後，會自動設定design型別的後設資料，透過以下方式可以獲取後設資料的值：

```
let result1 = Reflect.getMetadata('design:type', target, propertyKey);
let result2 = Reflect.getMetadata('design:paramtypes', target, propertyKey);
let result3 = Reflect.getMetadata('design:returntype', target, propertyKey);
```

不同型別的裝飾器獲得的 design 型別的後設資料值，如下表所示：

|裝飾器型別	| design:type|	design:paramtypes|	design:returntype|
|---|---|---|---|
|類裝飾器|		|建構函式所有引數型別組成的陣列|	|
|屬性裝飾器	|屬性的型別	|	|   |
|方法裝飾器	|Function	|方法所有引數的型別組成的陣列|方法返回值的型別|
|引數裝飾器	|所屬方法所有引數的型別組成的陣列|  |  |	
示例程式碼：

```
const MyClassDecorator: ClassDecorator = (target: any) => {
    const type = Reflect.getMetadata('design:type', target);
    console.log(`類[${target.name}] design:type = ${type && type.name}`);

const paramTypes = Reflect.getMetadata('design:paramtypes', target);
    console.log(`類[${target.name}] design:paramtypes =`, paramTypes && paramTypes.map(item => item.name));

const returnType = Reflect.getMetadata('design:returntype', target)
    console.log(`類[${target.name}] design:returntype = ${returnType && returnType.name}`);
};

const MyPropertyDecorator: PropertyDecorator = (target: any, key: string) => {
    const type = Reflect.getMetadata('design:type', target, key);
    console.log(`屬性[${key}] design:type = ${type && type.name}`);

const paramTypes = Reflect.getMetadata('design:paramtypes', target, key);
    console.log(`屬性[${key}] design:paramtypes =`, paramTypes && paramTypes.map(item => item.name));

const returnType = Reflect.getMetadata('design:returntype', target, key);
    console.log(`屬性[${key}] design:returntype = ${returnType && returnType.name}`);
};

const MyMethodDecorator: MethodDecorator = (target: any, key: string, descriptor: PropertyDescriptor) => {
    const type = Reflect.getMetadata('design:type', target, key);
    console.log(`方法[${key}] design:type = ${type && type.name}`);

const paramTypes = Reflect.getMetadata('design:paramtypes', target, key);
    console.log(`方法[${key}] design:paramtypes =`, paramTypes && paramTypes.map(item => item.name));

const returnType = Reflect.getMetadata('design:returntype', target, key)
    console.log(`方法[${key}] design:returntype = ${returnType && returnType.name}`);
};

const MyParameterDecorator: ParameterDecorator = (target: any, key: string, paramIndex: number) => {
    const type = Reflect.getMetadata('design:type', target, key);
    console.log(`引數[${key} - ${paramIndex}] design:type = ${type && type.name}`);

const paramTypes = Reflect.getMetadata('design:paramtypes', target, key);
    console.log(`引數[${key} - ${paramIndex}] design:paramtypes =`, paramTypes && paramTypes.map(item => item.name));

const returnType = Reflect.getMetadata('design:returntype', target, key)
    console.log(`引數[${key} - ${paramIndex}] design:returntype = ${returnType && returnType.name}`);
};

@MyClassDecorator
class MyClass {
    @MyPropertyDecorator
    myProperty: string;

constructor (myProperty: string) {
        this.myProperty = myProperty;
    }

@MyMethodDecorator
    myMethod (@MyParameterDecorator index: number, name: string): string {
        return `${index} - ${name}`;
    }
}

```

輸出結果如下：

```
屬性[myProperty] design:type = String
屬性[myProperty] design:paramtypes = undefined
屬性[myProperty] design:returntype = undefined
引數[myMethod - 0] design:type = Function
引數[myMethod - 0] design:paramtypes = [ 'Number', 'String' ]
引數[myMethod - 0] design:returntype = String
方法[myMethod] design:type = Function
方法[myMethod] design:paramtypes = [ 'Number', 'String' ]
方法[myMethod] design:returntype = String
類[MyClass] design:type = undefined
類[MyClass] design:paramtypes = [ 'String' ]
類[MyClass] design:returntype = undefined
```

### 四、	裝飾器應用
使用裝飾器可以實現自動註冊路由，透過給Controller層的類和方法新增裝飾器來定義路由資訊，當建立路由時掃描指定目錄下所有Controller，獲取裝飾器定義的路由資訊，從而實現自動新增路由。

### 裝飾器程式碼
- src/common/decorator/controller.ts

```
export interface Route {
    propertyKey: string,
    method: string;
    path: string;
}

export function Controller(path: string = ''): ClassDecorator {
    return (target: any) => {
        Reflect.defineMetadata('basePath', path, target);
    }
}

export type RouterDecoratorFactory = (path?: string) => MethodDecorator;

export function createRouterDecorator(method: string): RouterDecoratorFactory {
    return (path?: string) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => {
        const route: Route = {
            propertyKey,
            method,
            path: path || ''
        };
        if (!Reflect.hasMetadata('routes', target)) {
            Reflect.defineMetadata('routes', [], target);
        }
        const routes = Reflect.getMetadata('routes', target);
        routes.push(route);
    }
}

export const Get: RouterDecoratorFactory = createRouterDecorator('get');
export const Post: RouterDecoratorFactory = createRouterDecorator('post');
export const Put: RouterDecoratorFactory = createRouterDecorator('put');
export const Delete: RouterDecoratorFactory = createRouterDecorator('delete');
export const Patch: RouterDecoratorFactory = createRouterDecorator('patch');
```

### 控制器程式碼

- src/controller/roleController.ts

```
import Koa from 'koa';
import { Controller, Get } from '../common/decorator/controller';
import RoleService from '../service/roleService';

@Controller()
export default class RoleController {

@Get('/roles')
    static async getRoles (ctx: Koa.Context) {
        const roles = await RoleService.findRoles();
        ctx.body = roles;
    }

@Get('/roles/:id')
    static async getRoleById (ctx: Koa.Context) {
        const id = ctx.params.id;
        const role = await RoleService.findRoleById(id);
        ctx.body = role;
    }
}
```

- src/controller/userController.ts

```
import Koa from 'koa';
import { Controller, Get } from '../common/decorator/controller';
import UserService from '../service/userService';

@Controller('/users')
export default class UserController {
    @Get()
    static async getUsers (ctx: Koa.Context) {
        const users = await UserService.findUsers();
        ctx.body = users;
    }

@Get('/:id')
    static async getUserById (ctx: Koa.Context) {
        const id = ctx.params.id;
        const user = await UserService.findUserById(id);
        ctx.body = user;
    }
}
```

### 路由器程式碼

- src/common /scanRouter.ts

```
import fs from 'fs';
import path from 'path';
import KoaRouter from 'koa-router';
import { Route } from './decorator/controller';

// 掃描指定目錄的Controller並新增路由
function scanController(dirPath: string, router: KoaRouter): void {
    if (!fs.existsSync(dirPath)) {
        console.warn(`目錄不存在！${dirPath}`);
        return;
    }
    const fileNames: string[] = fs.readdirSync(dirPath);

for (const name of fileNames) {
        const curPath: string = path.join(dirPath, name);
        if (fs.statSync(curPath).isDirectory()) {
            scanController(curPath, router);
            continue;
        }
        if (!(/(.js|.jsx|.ts|.tsx)$/.test(name))) {
            continue;
        }
        try {
            const scannedModule = require(curPath);
            const controller = scannedModule.default || scannedModule;
            const isController: boolean = Reflect.hasMetadata('basePath', controller);
            const hasRoutes: boolean = Reflect.hasMetadata('routes', controller);
            if (isController && hasRoutes) {
                const basePath: string = Reflect.getMetadata('basePath', controller);
                const routes: Route[] = Reflect.getMetadata('routes', controller);
                let curPath: string, curRouteHandler;
                routes.forEach( (route: Route) => {
                    curPath = path.posix.join('/', basePath, route.path);
                    curRouteHandler = controller[route.propertyKey];
                    router[route.method](curPath, curRouteHandler);
                    console.info(`router: ${controller.name}.${route.propertyKey} [${route.method}] ${curPath}`)
                })
            }
        } catch (error) {
            console.warn('檔案讀取失敗！', curPath, error);
        }

}
}

export default class ScanRouter extends KoaRouter {
    constructor(opt?: KoaRouter.IRouterOptions) {
        super(opt);
    }

scan (scanDir: string | string[]) {
        if (typeof scanDir === 'string') {
            scanController(scanDir, this);
        } else if (scanDir instanceof Array) {
            scanDir.forEach(async (dir: string) => {
                scanController(dir, this);
            });
        }
    }
}
```

### 建立路由程式碼

- src/router.ts

```
import path from 'path';
import ScanRouter from './common/scanRouter';

const router = new ScanRouter();

router.scan([path.resolve(__dirname, './controller')]);

export default router;
```

### 五、	說明
本文介紹瞭如何在node服務中使用裝飾器，當需要增加某些額外的功能時，就可以不修改程式碼，簡單地透過新增裝飾器來實現功能。本文相關的程式碼已提交到GitHub以供參考，專案地址：[https://github.com/liulinsp/node-server-decorator-demo](https://github.com/liulinsp/node-server-decorator-demo)。

> 作者：宜信技術學院 劉琳</t></t></t></tfunction>

搭建node服務（四）：Decorator裝飾器

相關文章