Egg 插件

插件機制是我們框架的一大特色。它不但可以保證框架核心的足夠精簡、穩(wěn)定、高效，還可以促進業(yè)務邏輯的復用，生態(tài)圈的形成。有人可能會問了

• Koa 已經有了中間件的機制，為啥還要插件呢？
• 中間件、插件、應用它們之間是什么關系，有什么區(qū)別？
• 我該怎么使用一個插件？
• 如何編寫一個插件？
• ...

接下來我們就來逐一討論

為什么要插件

我們在使用 Koa 中間件過程中發(fā)現了下面一些問題：

1. 中間件加載其實是有先后順序的，但是中間件自身卻無法管理這種順序，只能交給使用者。這樣其實非常不友好，一旦順序不對，結果可能有天壤之別。
2. 中間件的定位是攔截用戶請求，并在它前后做一些事情，例如：鑒權、安全檢查、訪問日志等等。但實際情況是，有些功能是和請求無關的，例如：定時任務、消息訂閱、后臺邏輯等等。
3. 有些功能包含非常復雜的初始化邏輯，需要在應用啟動的時候完成。這顯然也不適合放到中間件中去實現。

綜上所述，我們需要一套更加強大的機制，來管理、編排那些相對獨立的業(yè)務邏輯。

中間件、插件、應用的關系

一個插件其實就是一個『迷你的應用』，和應用（app）幾乎一樣：

• 它包含了 Service、中間件、配置、框架擴展等等。
• 它沒有獨立的 Router 和 Controller。
• 它沒有 plugin.js，只能聲明跟其他插件的依賴，而不能決定其他插件的開啟與否。

他們的關系是：

• 應用可以直接引入 Koa 的中間件。
• 當遇到上一節(jié)提到的場景時，則應用需引入插件。
• 插件本身可以包含中間件。
• 多個插件可以包裝為一個上層框架。

使用插件

插件一般通過 npm 模塊的方式進行復用：

$ npm i egg-mysql --save

注意：我們建議通過 ^ 的方式引入依賴，并且強烈不建議鎖定版本。

{
  "dependencies": {
    "egg-mysql": "^3.0.0"
  }
}

然后需要在應用或框架的 config/plugin.js 中聲明：

// config/plugin.js
// 使用 mysql 插件
exports.mysql = {
  enable: true,
  package: 'egg-mysql',
};

就可以直接使用插件提供的功能：

app.mysql.query(sql, values);

參數介紹

plugin.js 中的每個配置項支持：

• {Boolean} enable - 是否開啟此插件，默認為 true
• {String} package - npm 模塊名稱，通過 npm 模塊形式引入插件
• {String} path - 插件絕對路徑，跟 package 配置互斥
• {Array} env - 只有在指定運行環(huán)境才能開啟，會覆蓋插件自身 package.json 中的配置

開啟和關閉

在上層框架內部內置的插件，應用在使用時就不用配置 package 或者 path，只需要指定 enable 與否：

// 對于內置插件，可以用下面的簡潔方式開啟或關閉
exports.onerror = false;

根據環(huán)境配置

同時，我們還支持 plugin.{env}.js 這種模式，會根據運行環(huán)境加載插件配置。

比如定義了一個開發(fā)環(huán)境使用的插件 egg-dev，只希望在本地環(huán)境加載，可以安裝到 devDependencies。

// npm i egg-dev --save-dev
// package.json
{
  "devDependencies": {
    "egg-dev": "*"
  }
}

然后在 plugin.local.js 中聲明：

// config/plugin.local.js
exports.dev = {
  enable: true,
  package: 'egg-dev',
};

這樣在生產環(huán)境可以 npm i --production 不需要下載 egg-dev 的包了。

注意:

• 不存在 plugin.default.js
• 只能在應用層使用，在框架層請勿使用。

package 和 path

• package 是 npm 方式引入，也是最常見的引入方式
• path 是絕對路徑引入，如應用內部抽了一個插件，但還沒達到開源發(fā)布獨立 npm 的階段，或者是應用自己覆蓋了框架的一些插件
• 關于這兩種方式的使用場景，可以參見漸進式開發(fā)。

// config/plugin.js
const path = require('path');
exports.mysql = {
  enable: true,
  path: path.join(__dirname, '../lib/plugin/egg-mysql'),
};

插件配置

插件一般會包含自己的默認配置，應用開發(fā)者可以在 config.default.js 覆蓋對應的配置：

// config/config.default.js
exports.mysql = {
  client: {
    host: 'mysql.com',
    port: '3306',
    user: 'test_user',
    password: 'test_password',
    database: 'test',
  },
};

具體合并規(guī)則可以參見配置。

插件列表

• 框架默認內置了企業(yè)級應用常用的插件：onerror 統(tǒng)一異常處理Session Session 實現i18n 多語言watcher 文件和文件夾監(jiān)控multipart 文件流式上傳security 安全development 開發(fā)環(huán)境配置logrotator 日志切分schedule 定時任務static 靜態(tài)服務器jsonp jsonp 支持view 模板引擎
• 更多社區(qū)的插件可以 GitHub 搜索 egg-plugin。

如何開發(fā)一個插件

參見文檔：插件開發(fā)。