docs: adjust middleware config at framework (#1523)

docs/source/en/basics/middleware.md

@@ -66,10 +66,10 @@ module.exports = options => {
 };
 ```
 
-## Using Middleware in the Application
+## Using Middleware in Application
 
 We can load customized middleware completely by configuration in the application, and decide their order.
-If we need to load the gzip middleware in the above, 
+If we need to load the gzip middleware in the above,
 we can edit `config.default.js` like this:
 
 ```js
@@ -84,26 +84,37 @@ module.exports = {
 };
 ```
 
-** About Configuration fields and runtime environment configurations, see [Config](./config.md) chapter. **
+This config will merge to `app.config.appMiddleware` on starting up.
 
-## Default Framework Middleware
+## Using Middleware in Framework and Plugin
 
-In addition to the application-level middleware is loaded, the framework itself and other plugins will also load many middleware. All the config fields of these built-in middlewares can be modified by modifying the ones with the same name in the config file, for example [Framework Built-in Plugin](https://github.com/eggjs/egg/tree/master/app/middleware) uses a bodyParser middleware(the framework loader will change the file name separated by delimiters into the camel style), and we can add configs below in `config/config.default.js` to modify the bodyParser:
+Framework and Plugin don't support `config.middleware`, you should mount it in `app.js`:
 
 ```js
-module.exports = {
-  bodyParser: {
-    jsonLimit: '10m',
-  },
+// app.js
+module.exports = app => {
+  // 在中间件最前面统计请求时间
+  app.config.coreMiddleware.unshift('report');
+};
+
+// app/middleware/report.js
+module.exports = () => {
+  return function* (next) {
+    const startTime = Date.now();
+    yield next;
+    // 上报请求时间
+    reportTime(Date.now() - startTime);
+  }
 };
 ```
-** Note: middleware loaded by the framework and plugins are loaded earlier than those loaded by the application layer, and the application layer cannot overwrite the default framework middleware. If the application layer loads customized middleware that has the same name with default framework middleware, an error will be raised on starting up. **
 
-## Middleware in Router
+Middlewares which defined at Application (`app.config.coreMiddleware`) and Framework(`app.config.coreMiddleware`) will be merge to `app.middleware` by loader at staring up.
 
-Both middleware defined by the application layer and the default framework middleware will be loaded by the loader and are mounted to `app.middlewares`(Note: it's plural here since `app.middleware` is used for other purpose in Koa). So middleware defined by the application layer can be loaded by the router other than the config, therefore they only take effect on the corresponding routes.
+## Using Middleware in Router
 
-Again, let's take the gzip middleware above for an example. In order to use this middleware directly in the router, we can write like this in `app/router.js`:
+Both middleware defined by the application layer and the default framework middleware is global, will process every request.
+
+If you do want to take effect on the corresponding routes, you could just mount it at `app/router.js`:
 
 ```js
 module.exports = app => {
@@ -112,9 +123,24 @@ module.exports = app => {
 };
 ```
 
+## Default Framework Middleware
+
+In addition to the application-level middleware is loaded, the framework itself and other plugins will also load many middleware. All the config fields of these built-in middlewares can be modified by modifying the ones with the same name in the config file, for example [Framework Built-in Plugin](https://github.com/eggjs/egg/tree/master/app/middleware) uses a bodyParser middleware(the framework loader will change the file name separated by delimiters into the camel style), and we can add configs below in `config/config.default.js` to modify the bodyParser:
+
+```js
+module.exports = {
+  bodyParser: {
+    jsonLimit: '10m',
+  },
+};
+```
+
+** Note: middleware loaded by the framework and plugins are loaded earlier than those loaded by the application layer, and the application layer cannot overwrite the default framework middleware. If the application layer loads customized middleware that has the same name with default framework middleware, an error will be raised on starting up. **
+
+
 ## Use Koa's Middleware
 
-The framework is compatible with all kinds of middleware of Koa 1.x and 2.x, including: 
+The framework is compatible with all kinds of middleware of Koa 1.x and 2.x, including:
 - generator function: `function* (next) {}`
 - async function: `async (ctx, next) => {}`
 - common function: `(ctx, next) => {}`

docs/source/zh-cn/basics/middleware.md

@@ -84,7 +84,11 @@ module.exports = {
 };
 ```
 
-我们还可以动态修改现有中间件的顺序，中间件的加载顺序和插件顺序不同，是由 `app.config.coreMiddleware` 和 `app.config.appMiddleware` 这两个数组合并而成的。
+该配置最终将在启动时合并到 `app.config.appMiddleware`。
+
+## 在框架和插件中使用中间件
+
+框架和插件不支持在 `config.default.js` 中匹配 `middleware`，需要通过以下方式：
 
 ```js
 // app.js
@@ -104,7 +108,19 @@ module.exports = () => {
 };
 ```
 
-**配置项以及区分各运行环境的配置，请查看[配置](./config.md)章节。**
+应用层定义的中间件（`app.config.appMiddleware`）和框架默认中间件（`app.config.coreMiddleware`）都会被加载器加载，并挂载到 `app.middleware` 上。
+
+## router 中使用中间件
+
+以上两种方式配置的中间件是全局的，会处理每一次请求。
+如果你只想针对单个路由生效，可以直接在 `app/router.js` 中实例化和挂载，如下：
+
+```js
+module.exports = app => {
+  const gzip = app.middlewares.gzip({ threshold: 1024 });
+  app.get('/needgzip', gzip, app.controller.handler);
+};
+```
 
 ## 框架默认中间件
 
@@ -120,19 +136,6 @@ module.exports = {
 
 **注意：框架和插件加载的中间件会在应用层配置的中间件之前，框架默认中间件不能被应用层中间件覆盖，如果应用层有自定义同名中间件，在启动时会报错。**
 
-## router 中使用中间件
-
-应用层定义的中间件和框架默认中间件都会被加载器加载，并挂载到 `app.middlewares` 上（注意：此处为复数，因为 `app.middleware` 在 Koa 中另有用处），所以应用层定义的中间件可以不通过配置加载，而是在 router 中加载，从而只对对应的路由生效。
-
-还是拿刚才的 gzip 中间件举例，当我们想直接在 router 中使用的时候，在 `app/router.js` 中就可以这样写
-
-```js
-module.exports = app => {
-  const gzip = app.middlewares.gzip({ threshold: 1024 });
-  app.get('/needgzip', gzip, app.controller.handler);
-};
-```
-
 ## 使用 Koa 的中间件
 
 框架兼容 Koa 1.x 和 2.x 支持的所有形式的中间件，包括：