egg-shell-decorators 給你的蛋蛋加個殼

Egg.js 路由裝飾器，讓你的開發更敏捷~

【PS：文末有本人聯繫方式，歡迎技術交流~】

egg-shell-decorators 是一個 Egg.js 的插件，它提供了一系列的 Decorator 裝飾 Controller，讓咱們先來看一個例子：

// app/controller/user
import { Controller } from 'egg';
import { Get, Message } from 'egg-shell-decorators';

export default class UserController extends Controller {

  @Get('/detail/:id')
  @Message('so great !')
  public async get({ params: { id } }) {
    return await this.service.user.getById(id)
  }

}

上面是一個簡單的控制器例子，若是是 egg.js 的默認開發方式，那麼你得在 router 文件對相應的路由進行映射，而使用 egg-shell-decorators 以後，不再用在 router 文件進行任何路由匹配了。由於 egg-shell-decorators 的路由解析會自動對路由進行解析，像上面這個例子會自動解析成 [get] 全局前綴 + /user/detail/:id，這樣咱們開發者就不用再去操心映射的問題了，並且在 Controller 裏咱們就能夠知道每個函數對應的請求信息。

也許你會疑惑上面的@Message還有爲何直接把查詢到的數據 return 了是怎麼回事，如今我將系統的向你介紹該插件的使用：

Installation

$ npm install egg-shell-decorators -S

若是不是採用 TypeScript 腳手架，則需執行如下腳本安裝相關的 Babel 插件：

$ npm install babel-register babel-plugin-transform-decorators-legacy -D

Usage

示範代碼均採用 TypeScript

// app/router.ts
import { Application } from 'egg';
import { EggShell } from 'egg-shell-decorators';

export default (app: Application) => {
  EggShell(app, { prefix: '/', quickStart: true });
};

配置參數：

prefix: string // 全局前綴
quickStart: boolean // 開啓QuickStart

若是不是採用 TypeScript 腳手架，則需在入口註冊 Bable 插件使其支持 Decorator：

// app.js
'use strict';
require('babel-register')({
  plugins: [
    'transform-decorators-legacy',
  ],
});

Specialty

路由解析是 egg-shell-decorators 最大的特色，使用 Decorator 裝飾的路由，則會被自動解析成對應的路由：

• 文件路徑：app/controller/home.ts

  • @Get('/detail/:id')
  • @Post('/')

• 解析路由：

  • [get] 全局前綴 + /home + /detail/:id
  • [post] 全局前綴 + /home + /

這裏的 全局前綴 指的是你在 EggShell 裏配置的 prefix，路由解析支持多層級解析噢~

Member

• Http相關

  • ✅Get
  • ✅Post
  • ✅Put
  • ✅Delete
  • ✅Patch
  • ✅Options
  • ✅Head
  • 🔲Header

• 中間件相關

  • ✅Before
  • ✅After
  • ✅BeforeAll
  • ✅AfterAll

• Swagger相關

  • 🔲敬請期待下一個版本

• 其餘

  • ✅Prefix
  • ✅Message
  • ✅IgnoreJwt
  • ✅IgnoreJwtAll

Prefix

若是你不喜歡路由解析給你的路徑，那麼你能夠自定義解析的路徑：

// app/controller/user
import { Controller } from 'egg';
import { Get, Message, Prefix } from 'egg-shell-decorators';

@Prefix('/super2god')
export default class UserController extends Controller {

  @Get('/detail/:id')
  @Message('so great !')
  public async get({ params: { id } }) {
    return await this.service.user.getById(id)
  }

}

這樣解析出來的路由就是：全局前綴 + /super2god/detail/:id，而不是全局前綴 + /user/detail/:id

QuickStart

在 EggShell 裏配置 quickStart 爲 true 便可開啓 QuickStart 模式，QuickStart 模式會自動處理響應體：

import { Controller } from 'egg';
import { Get, Message, Error, StatusError } from 'egg-shell-decorators';

export default class UserController extends Controller {

  /**
   status: 200
   {
     success: true,
     message: '棒棒噠',
     data: {
       id: '123',
       name: 'super2god'
     },
   }
   */
  @Get('/:id')
  @Message('棒棒噠')
  public async get({ params: { id } }) {
    return await this.service.user.getById(id)
  }

  /**
   status: 200
   {
     success: false,
     message: '故意的'
   }
   */
  @Post('/:id')
  public post() {
    throw Error('故意的')
  }

  /**
   status: 403
   {
     success: false,
     message: '權限不足'
   }
   */
  @Post('/:id')
  public post() {
    // StatusError 的第二個參數默認值爲500
    throw StatusError('權限不足', 403)
  }

}

RESTful

讓咱們用 egg-shell-decorators 快速寫一套 RESTful 風格的接口（QuickStart 模式）：

import { Controller } from 'egg';
import { Get, Post, Put, Delete } from 'egg-shell-decorators';

export default class SubOrderController extends Controller {

  @Get('/:id')
  public get({ params: { id }, query: { keyword } }) {
    return `resuful get : ${id}, ${keyword}`;
  }

  @Post('/:id')
  public post({ params: { id }, request: { body: { keyword } } }) {
    return `resuful post : ${id}, ${keyword}`;
  }

  @Put('/:id')
  public put({ params: { id }, request: { body: { keyword } } }) {
    return `resuful put : ${id}, ${keyword}`;
  }

  @Delete('/:id')
  public delete({ params: { id }, request: { body: { keyword } } }) {
    return `resuful delete : ${id}, ${keyword}`;
  }

}

因爲 egg-shell-decorators 內置把 ctx 對象傳進 Controller 的函數裏了，因此咱們直接結構就能夠獲取到請求參數了，美滋滋~

固然，除了這四個經常使用的請求方法，egg-shell-decorators 還提供了其餘比較經常使用的請求方法，具體請看上面的Http請求方法。

Jwt

Jwt是目前比較流行的身份認證機制，因此 egg-shell-decorators 提供了相關的 Decorator。若是你使用了 egg-jwt，那默認因此路由都須要進行身份校驗，而有時咱們想讓部分路由不用校驗，那麼你只需那麼作：

import { Controller } from 'egg';
import { Get, IgnoreJwt } from 'egg-shell-decorators';

export default class HomeController extends Controller {

  @IgnoreJwt
  @Get('/')
  public async index() {
    return 'hi, egg';
  }

}

是否是很簡單呢，若是你想對整個 Controller 都進行校驗忽略，那也很簡單：

import { Controller } from 'egg';
import { Get, Post, IgnoreJwtAll } from 'egg-shell-decorators';

@IgnoreJwtAll
export default class HomeController extends Controller {

  @Get('/')
  public async get() {
    return 'get';
  }

  @Post('/')
  public async post() {
    return 'post';
  }

}

MiddleWare

egg-shell-decorators 提供了四個中間件相關的 Decorator，讓你使用中間件更簡單：

import { Controller } from 'egg';
import { Get, IgnoreJwtAll, Before, After, BeforeAll, AfterAll } from 'egg-shell-decorators';

const Before1 = require('egg-shell-decorators/test/middlewares/before-1');
const Before2 = require('egg-shell-decorators/test/middlewares/before-2');
const Before3 = require('egg-shell-decorators/test/middlewares/before-3');
const Before4 = require('egg-shell-decorators/test/middlewares/before-4');

const After1 = require('egg-shell-decorators/test/middlewares/after-1');
const After2 = require('egg-shell-decorators/test/middlewares/after-2');
const After3 = require('egg-shell-decorators/test/middlewares/after-3');
const After4 = require('egg-shell-decorators/test/middlewares/after-4');

@BeforeAll([ Before1, Before2 ])
@AfterAll([ After1, After2 ])
@IgnoreJwtAll
export default class HomeController extends Controller {

  /**
   before middleware => 1
   before middleware => 2
   before middleware => 3
   before middleware => 4
   主業務...
   after middleware => 1
   after middleware => 2
   after middleware => 3
   after middleware => 4
   */
  @Before([ Before3, Before4 ])
  @After([ After3, After4 ])
  @Get('/')
  public async index() {
    return 'hi, egg';
  }

}

egg-shell-decorators 的用法都已經介紹完畢了，若是你是一名 Noder 或者熱愛 Egg.js 的小夥伴，那麼能夠加我微信進行技術交流，讓咱們一塊兒變得更優秀：