title: 中间件（Middleware）

在前面的章节中，我们介绍了 Egg 是基于 Koa 实现的，所以 Egg 的中间件形式和 Koa 的中间件形式是一样的，都是基于洋葱圈模型。每次我们编写一个中间件，就相当于在洋葱外面包了一层。

编写中间件

写法

我们先来通过编写一个简单的 gzip 中间件，来看看中间件的写法。

  1. // app/middleware/gzip.js
  2. const isJSON = require('koa-is-json');
  3. const zlib = require('zlib');
  5. async function gzip(ctx, next) {
  6.   await next();
  8.   // 后续中间件执行完成后将响应体转换成 gzip
  9.   let body = ctx.body;
  10.   if (!body) return;
  11.   if (isJSON(body)) body = JSON.stringify(body);
  13.   // 设置 gzip body，修正响应头
  14.   const stream = zlib.createGzip();
  15.   stream.end(body);
  16.   ctx.body = stream;
  17.   ctx.set('Content-Encoding', 'gzip');
  18. }

可以看到，框架的中间件和 Koa 的中间件写法是一模一样的，所以任何 Koa 的中间件都可以直接被框架使用。

配置

一般来说中间件也会有自己的配置。在框架中，一个完整的中间件是包含了配置处理的。我们约定一个中间件是一个放置在 app/middleware 目录下的单独文件，它需要 exports 一个普通的 function，接受两个参数：

  • options: 中间件的配置项，框架会将 app.config[${middlewareName}] 传递进来。
  • app: 当前应用 Application 的实例。

我们将上面的 gzip 中间件做一个简单的优化，让它支持指定只有当 body 大于配置的 threshold 时才进行 gzip 压缩，我们要在 app/middleware 目录下新建一个文件 gzip.js

  1. // app/middleware/gzip.js
  2. const isJSON = require('koa-is-json');
  3. const zlib = require('zlib');
  5. module.exports = options => {
  6.   return async function gzip(ctx, next) {
  7.     await next();
  9.     // 后续中间件执行完成后将响应体转换成 gzip
  10.     let body = ctx.body;
  11.     if (!body) return;
  13.     // 支持 options.threshold
  14.     if (options.threshold && ctx.length < options.threshold) return;
  16.     if (isJSON(body)) body = JSON.stringify(body);
  18.     // 设置 gzip body，修正响应头
  19.     const stream = zlib.createGzip();
  20.     stream.end(body);
  21.     ctx.body = stream;
  22.     ctx.set('Content-Encoding', 'gzip');
  23.   };
  24. };

使用中间件

中间件编写完成后，我们还需要手动挂载，支持以下方式：

在应用中使用中间件

在应用中，我们可以完全通过配置来加载自定义的中间件，并决定它们的顺序。

如果我们需要加载上面的 gzip 中间件，在 config.default.js 中加入下面的配置就完成了中间件的开启和配置：

  1. module.exports = {
  2.   // 配置需要的中间件，数组顺序即为中间件的加载顺序
  3.   middleware: [ 'gzip' ],
  5.   // 配置 gzip 中间件的配置
  6.   gzip: {
  7.     threshold: 1024, // 小于 1k 的响应体不压缩
  8.   },
  9. };

该配置最终将在启动时合并到 app.config.appMiddleware。

在框架和插件中使用中间件

框架和插件不支持在 config.default.js 中匹配 middleware，需要通过以下方式：

  1. // app.js
  2. module.exports = app => {
  3.   // 在中间件最前面统计请求时间
  4.   app.config.coreMiddleware.unshift('report');
  5. };
  7. // app/middleware/report.js
  8. module.exports = () => {
  9.   return async function (ctx, next) {
  10.     const startTime = Date.now();
  11.     await next();
  12.     // 上报请求时间
  13.     reportTime(Date.now() - startTime);
  14.   }
  15. };

应用层定义的中间件（app.config.appMiddleware）和框架默认中间件（app.config.coreMiddleware）都会被加载器加载，并挂载到 app.middleware 上。

router 中使用中间件

以上两种方式配置的中间件是全局的，会处理每一次请求。 如果你只想针对单个路由生效，可以直接在 app/router.js 中实例化和挂载，如下：

  1. module.exports = app => {
  2.   const gzip = app.middleware.gzip({ threshold: 1024 });
  3.   app.router.get('/needgzip', gzip, app.controller.handler);
  4. };

框架默认中间件

除了应用层加载中间件之外，框架自身和其他的插件也会加载许多中间件。所有的这些自带中间件的配置项都通过在配置中修改中间件同名配置项进行修改，例如框架自带的中间件中有一个 bodyParser 中间件（框架的加载器会将文件名中的各种分隔符都修改成驼峰形式的变量名），我们想要修改 bodyParser 的配置，只需要在 config/config.default.js 中编写

  1. module.exports = {
  2.   bodyParser: {
  3.     jsonLimit: '10mb',
  4.   },
  5. };

注意：框架和插件加载的中间件会在应用层配置的中间件之前，框架默认中间件不能被应用层中间件覆盖，如果应用层有自定义同名中间件，在启动时会报错。

使用 Koa 的中间件

在框架里面可以非常容易的引入 Koa 中间件生态。

以 koa-compress 为例，在 Koa 中使用时：

  1. const koa = require('koa');
  2. const compress = require('koa-compress');
  4. const app = koa();
  6. const options = { threshold: 2048 };
  7. app.use(compress(options));

我们按照框架的规范来在应用中加载这个 Koa 的中间件：

  1. // app/middleware/compress.js
  2. // koa-compress 暴露的接口(`(options) => middleware`)和框架对中间件要求一致
  3. module.exports = require('koa-compress');
  1. // config/config.default.js
  2. module.exports = {
  3.   middleware: [ 'compress' ],
  4.   compress: {
  5.     threshold: 2048,
  6.   },
  7. };

如果使用到的 Koa 中间件不符合入参规范，则可以自行处理下：

  1. // config/config.default.js
  2. module.exports = {
  3.   webpack: {
  4.     compiler: {},
  5.     others: {},
  6.   },
  7. };
  9. // app/middleware/webpack.js
  10. const webpackMiddleware = require('some-koa-middleware');
  12. module.exports = (options, app) => {
  13.   return webpackMiddleware(options.compiler, options.others);
  14. }

通用配置

无论是应用层加载的中间件还是框架自带中间件，都支持几个通用的配置项：

  • enable：控制中间件是否开启。
  • match：设置只有符合某些规则的请求才会经过这个中间件。
  • ignore：设置符合某些规则的请求不经过这个中间件。

enable

如果我们的应用并不需要默认的 bodyParser 中间件来进行请求体的解析，此时我们可以通过配置 enable 为 false 来关闭它

  1. module.exports = {
  2.   bodyParser: {
  3.     enable: false,
  4.   },
  5. };

match 和 ignore

match 和 ignore 支持的参数都一样，只是作用完全相反，match 和 ignore 不允许同时配置。

如果我们想让 gzip 只针对 /static 前缀开头的 url 请求开启，我们可以配置 match 选项

  1. module.exports = {
  2.   gzip: {
  3.     match: '/static',
  4.   },
  5. };

match 和 ignore 支持多种类型的配置方式

  1. 字符串：当参数为字符串类型时，配置的是一个 url 的路径前缀，所有以配置的字符串作为前缀的 url 都会匹配上。 当然，你也可以直接使用字符串数组。
  2. 正则：当参数为正则时，直接匹配满足正则验证的 url 的路径。
  3. 函数：当参数为一个函数时，会将请求上下文传递给这个函数，最终取函数返回的结果（true/false）来判断是否匹配。
  1. module.exports = {
  2.   gzip: {
  3.     match(ctx) {
  4.       // 只有 ios 设备才开启
  5.       const reg = /iphone|ipad|ipod/i;
  6.       return reg.test(ctx.get('user-agent'));
  7.     },
  8.   },
  9. };

有关更多的 match 和 ignore 配置情况，详见 egg-path-matching.