feat: 优化中文文档表达 (#5290)

Co-authored-by: xiaofeng.mxf <xiaofeng.mxf@antgroup.com>

Author: ottomao

site/docs/basics/app-start.zh-CN.md

@@ -3,21 +3,20 @@ title: 启动自定义
 order: 12
 ---
 
-我们常常需要在应用启动期间进行一些初始化工作，等初始化完成后应用才可以启动成功，并开始对外提供服务。
+我们常常需要在应用启动期间进行一些初始化工作，待初始化完成后，应用才可以启动成功，并开始对外提供服务。
 
-框架提供了统一的入口文件（`app.js`）进行启动过程自定义，这个文件返回一个 Boot 类，我们可以通过定义 Boot 类中的生命周期方法来执行启动应用过程中的初始化工作。
+框架提供了统一的入口文件（`app.js`）进行启动过程自定义。这个文件需要返回一个 Boot 类。我们可以通过定义 Boot 类中的生命周期方法来执行启动应用过程中的初始化工作。
 
-框架提供了这些 [生命周期函数](../advanced/loader.md#life-cycles)供开发人员处理：
+框架提供了以下 [生命周期函数](../advanced/loader.md#life-cycles) 供开发人员处理：
+- 配置文件即将加载，这是最后动态修改配置的时机（`configWillLoad`）；
+- 配置文件加载完成（`configDidLoad`）；
+- 文件加载完成（`didLoad`）；
+- 插件启动完毕（`willReady`）；
+- worker 准备就绪（`didReady`）；
+- 应用启动完成（`serverDidReady`）；
+- 应用即将关闭（`beforeClose`）。
 
-- 配置文件即将加载，这是最后动态修改配置的时机（`configWillLoad`）
-- 配置文件加载完成（`configDidLoad`）
-- 文件加载完成（`didLoad`）
-- 插件启动完毕（`willReady`）
-- worker 准备就绪（`didReady`）
-- 应用启动完成（`serverDidReady`）
-- 应用即将关闭（`beforeClose`）
-
-我们可以在 `app.js` 中定义这个 Boot 类，下面我们抽取几个在应用开发中常用的生命周期函数来举例：
+我们可以在 `app.js` 中定义这个 Boot 类。下面我们抽取几个在应用开发中常用的生命周期函数为例：
 
 ```js
 // app.js
@@ -27,8 +26,8 @@ class AppBootHook {
   }
 
   configWillLoad() {
-    // 此时 config 文件已经被读取并合并，但是还并未生效
-    // 这是应用层修改配置的最后时机
+    // 此时 config 文件已经被读取并合并，但还并未生效
+    // 这是应用层修改配置的最后机会
     // 注意：此函数只支持同步调用
 
     // 例如：参数中的密码是加密的，在此处进行解密
@@ -39,47 +38,47 @@ class AppBootHook {
   }
 
   async didLoad() {
-    // 所有的配置已经加载完毕
-    // 可以用来加载应用自定义的文件，启动自定义的服务
+    // 所有配置已经加载完毕
+    // 可以用来加载应用自定义的文件，启动自定义服务
 
-    // 例如：创建自定义应用的示例
+    // 例如：创建自定义应用的实例
     this.app.queue = new Queue(this.app.config.queue);
     await this.app.queue.init();
 
-    // 例如：加载自定义的目录
+    // 例如：加载自定义目录
     this.app.loader.loadToContext(path.join(__dirname, 'app/tasks'), 'tasks', {
       fieldClass: 'tasksClasses',
     });
   }
 
   async willReady() {
-    // 所有的插件都已启动完毕，但是应用整体还未 ready
-    // 可以做一些数据初始化等操作，这些操作成功才会启动应用
+    // 所有插件已启动完毕，但应用整体尚未 ready
+    // 可进行数据初始化等操作，这些操作成功后才启动应用
 
     // 例如：从数据库加载数据到内存缓存
     this.app.cacheData = await this.app.model.query(QUERY_CACHE_SQL);
   }
 
   async didReady() {
-    // 应用已经启动完毕
+    // 应用已启动完毕
 
     const ctx = await this.app.createAnonymousContext();
     await ctx.service.Biz.request();
   }
 
   async serverDidReady() {
-    // http / https server 已启动，开始接受外部请求
-    // 此时可以从 app.server 拿到 server 的实例
+    // http/https 服务器已启动，开始接收外部请求
+    // 此时可以从 app.server 获取 server 实例
 
-    this.app.server.on('timeout', (socket) => {
-      // handle socket timeout
+    this.app.server.on('timeout', socket => {
+      // 处理 socket 超时
     });
   }
 }
 
 module.exports = AppBootHook;
 ```
 
-**注意：在自定义生命周期函数中不建议做太耗时的操作，框架会有启动的超时检测。**
+**注意：在自定义生命周期函数中，不建议进行耗时的操作，因为框架会有启动的超时检测。**
 
-如果你的 Egg 框架的生命周期函数是旧版本的，建议你升级到类方法模式；详情请查看[升级你的生命周期事件函数](../advanced/loader-update.md)。
+如果你的 Egg 框架的生命周期函数是旧版本的，建议你将其升级到类方法模式；详情请查看[升级你的生命周期事件函数](../advanced/loader-update.md)。

site/docs/basics/config.zh-CN.md

@@ -5,17 +5,16 @@ order: 4
 
 框架提供了强大且可扩展的配置功能，可以自动合并应用、插件、框架的配置，按顺序覆盖，且可以根据环境维护不同的配置。合并后的配置可直接从 `app.config` 获取。
 
-配置的管理有多种方案，以下列一些常见的方案
+配置的管理有多种方案，以下列举一些常见的方案：
 
-1. 使用平台管理配置，应用构建时将当前环境的配置放入包内，启动时指定该配置。但应用就无法一次构建多次部署，而且本地开发环境想使用配置会变的很麻烦。
-1. 使用平台管理配置，在启动时将当前环境的配置通过环境变量传入，这是比较优雅的方式，但框架对运维的要求会比较高，需要部署平台支持，同时开发环境也有相同痛点。
-1. 使用代码管理配置，在代码中添加多个环境的配置，在启动时传入当前环境的参数即可。但无法全局配置，必须修改代码。
-
-我们选择了最后一种配置方案，**配置即代码**，配置的变更也应该经过 review 后才能发布。应用包本身是可以部署在多个环境的，只需要指定运行环境即可。
+1. 使用平台管理配置，应用构建时将当前环境的配置放入包内，启动时指定该配置。但应用就无法一次构建多次部署，而且本地开发环境想使用配置会变得很麻烦。
+2. 使用平台管理配置，在启动时将当前环境的配置通过环境变量传入，这是比较优雅的方式，但框架对运维的要求会比较高，需要部署平台支持，同时开发环境也有相同的痛点。
+3. 使用代码管理配置，在代码中添加多个环境的配置，在启动时传入当前环境的参数即可。但无法全局配置，必须修改代码。
 
+我们选择了最后一种配置方案，**配置即代码**，配置的变更也应该经过审核后才能发布。应用包本身是可以部署在多个环境的，只需要指定运行环境即可。
 ### 多环境配置
 
-框架支持根据环境来加载配置，定义多个环境的配置文件，具体环境请查看[运行环境配置](./env.md)
+框架支持根据环境来加载配置，定义多个环境的配置文件，具体环境请查看[运行环境配置](./env.md)。
 
 ```
 config
@@ -27,11 +26,10 @@ config
 
 `config.default.js` 为默认的配置文件，所有环境都会加载这个配置文件，一般也会作为开发环境的默认配置文件。
 
-当指定 env 时会同时加载默认配置和对应的配置(具名配置)文件，具名配置和默认配置将合并(使用[extend2](https://www.npmjs.com/package/extend2)深拷贝)成最终配置，具名配置项会覆盖默认配置文件的同名配置。如 `prod` 环境会加载 `config.prod.js` 和 `config.default.js` 文件，`config.prod.js` 会覆盖 `config.default.js` 的同名配置。
-
+当指定 `env` 时，会同时加载默认配置和对应的配置（具名配置）文件。具名配置和默认配置将合并（使用 [extend2](https://www.npmjs.com/package/extend2) 深拷贝）成最终配置，具名配置项会覆盖默认配置文件的同名配置。例如，`prod` 环境会加载 `config.prod.js` 和 `config.default.js` 文件，`config.prod.js` 会覆盖 `config.default.js` 的同名配置。
 ### 配置写法
 
-配置文件返回的是一个 object 对象，可以覆盖框架的一些配置，应用也可以将自己业务的配置放到这里方便管理。
+配置文件返回的是一个对象，可以覆盖框架的一些配置，应用也可以将自己业务的配置放到这里方便管理。
 
 ```js
 // 配置 logger 文件的目录，logger 默认配置由框架提供
@@ -42,7 +40,7 @@ module.exports = {
 };
 ```
 
-配置文件也可以简化的写成 `exports.key = value` 形式
+配置文件也可以简化地写成 `exports.key = value` 形式：
 
 ```js
 exports.keys = 'my-cookie-secret-key';
@@ -51,7 +49,7 @@ exports.logger = {
 };
 ```
 
-配置文件也可以返回一个 function，可以接受 appInfo 参数
+配置文件也可以返回一个函数，该函数可以接受 `appInfo` 参数：
 
 ```js
 // 将 logger 目录放到代码目录下
@@ -65,22 +63,22 @@ module.exports = (appInfo) => {
 };
 ```
 
-内置的 appInfo 有
+内置的 `appInfo` 属性包括：
 
-| appInfo | 说明                                                                   |
-| ------- | ---------------------------------------------------------------------- |
-| pkg     | package.json                                                           |
-| name    | 应用名，同 pkg.name                                                    |
-| baseDir | 应用代码的目录                                                         |
-| HOME    | 用户目录，如 admin 账户为 /home/admin                                  |
-| root    | 应用根目录，只有在 local 和 unittest 环境下为 baseDir，其他都为 HOME。 |
+| appInfo | 说明                                                         |
+| ------- | ------------------------------------------------------------ |
+| pkg     | `package.json` 文件                                           |
+| name    | 应用名称，同 `pkg.name`                                      |
+| baseDir | 应用代码的目录                                               |
+| HOME    | 用户目录，如 admin 账户为 `/home/admin`                      |
+| root    | 应用根目录，在 `local` 和 `unittest` 环境下为 `baseDir`，其他都为 `HOME`。 |
 
-`appInfo.root` 是一个优雅的适配，比如在服务器环境我们会使用 `/home/admin/logs` 作为日志目录，而本地开发时又不想污染用户目录，这样的适配就很好解决这个问题。
+`appInfo.root` 是一个优雅的适配方案。例如，在服务器环境我们通常使用 `/home/admin/logs` 作为日志目录，而在本地开发时为了避免污染用户目录，我们需要一种优雅的适配方案，`appInfo.root` 正好解决了这个问题。
 
-请根据具体场合选择合适的写法，但请确保没有写出以下代码：
+请根据具体场合选择合适的写法。但请确保没有完成以下代码：
 
 ```js
-// config/config.default.js
+// 配置文件 config/config.default.js
 exports.someKeys = 'abc';
 module.exports = (appInfo) => {
   const config = {};
@@ -91,9 +89,9 @@ module.exports = (appInfo) => {
 
 ### 配置加载顺序
 
-应用、插件、框架都可以定义这些配置，而且目录结构都是一致的，但存在优先级（应用 > 框架 > 插件），相对于此运行环境的优先级会更高。
+应用、插件、框架都可以定义这些配置，且目录结构都是一致的，但存在优先级（应用 > 框架 > 插件），相对于此运行环境的优先级会更高。
 
-比如在 prod 环境加载一个配置的加载顺序如下，后加载的会覆盖前面的同名配置。
+比如在 prod 环境中加载一个配置的加载顺序如下，后加载的会覆盖前面的同名配置。
 
 ```
 -> 插件 config.default.js
@@ -104,11 +102,10 @@ module.exports = (appInfo) => {
 -> 应用 config.prod.js
 ```
 
-**注意：插件之间也会有加载顺序，但大致顺序类似，具体逻辑可[查看加载器](../advanced/loader.md)。**
-
+**注意**：插件之间也会有加载顺序，但大致顺序类似。具体逻辑可[查看加载器](../advanced/loader.md)。
 ### 合并规则
 
-配置的合并使用 [extend2] 模块进行深度拷贝，[extend2] fork 自 [extend]，处理数组时会存在差异。
+配置的合并使用 `extend2` 模块进行深度拷贝，`extend2` 来源于 `extend`，但是在处理数组时的表现会有所不同。
 
 ```js
 const a = {
@@ -125,14 +122,14 @@ extend(true, a, b);
 
 ### 配置结果
 
-框架在启动时会把合并后的最终配置 dump 到 `run/application_config.json`（worker 进程）和 `run/agent_config.json`（agent 进程）中，可以用来分析问题。
+框架在启动时会把合并后的最终配置输出到 `run/application_config.json`（worker 进程）和 `run/agent_config.json`（agent 进程）中，以供问题分析。
 
-配置文件中会隐藏一些字段，主要包括两类:
+配置文件中会隐藏以下两类字段：
 
-- 如密码、密钥等安全字段，这里可以通过 `config.dump.ignore` 配置，必须是 [Set] 类型，查看[默认配置](https://github.com/eggjs/egg/blob/master/config/config.default.js)。
-- 如函数、Buffer 等类型，`JSON.stringify` 后的内容特别大
+1. 安全字段，如密码、密钥等。这些字段通过 `config.dump.ignore` 属性进行配置，其类型必须是 [Set]。可参见[默认配置](https://github.com/eggjs/egg/blob/master/config/config.default.js)。
+2. 非字符串化字段，如函数、Buffer 等。这些字段在 `JSON.stringify` 后所生成的内容容量很大。
 
-还会生成 `run/application_config_meta.json`（worker 进程）和 `run/agent_config_meta.json`（agent 进程）文件，用来排查属性的来源，如
+此外，框架还会生成 `run/application_config_meta.json`（worker 进程）和 `run/agent_config_meta.json`（agent 进程）文件。这些文件用于排查配置属性的来源，例如：
 
 ```json
 {
@@ -142,6 +139,6 @@ extend(true, a, b);
 }
 ```
 
-[set]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
+[Set]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
 [extend]: https://github.com/justmoon/node-extend
 [extend2]: https://github.com/eggjs/extend2

site/docs/basics/controller.zh-CN.md

@@ -9,9 +9,9 @@ order: 3
 
 框架有两种方式指定运行环境：
 
-1. 通过  `config/env` 文件指定，该文件的内容就是运行环境，如 `prod`。一般通过构建工具来生成这个文件。
+1. 通过 `config/env` 文件指定，该文件的内容就是运行环境，如 `prod`。一般通过构建工具来生成这个文件。
 
-```
+```plaintext
 // config/env
 prod
 ```
@@ -24,32 +24,29 @@ EGG_SERVER_ENV=prod npm start
 
 ## 应用内获取运行环境
 
-框架提供了变量 `app.config.env` 来表示应用当前的运行环境。
-
+框架提供了变量 `app.config.env`，来表示应用当前的运行环境。
 ## 运行环境相关配置
 
 不同的运行环境会对应不同的配置，具体请阅读 [Config 配置](./config.md)。
+## 与 `NODE_ENV` 的区别
 
-## 与 NODE_ENV 的区别
+很多 Node.js 应用会使用 `NODE_ENV` 来区分运行环境，但 `EGG_SERVER_ENV` 区分得更加精细。一般的项目开发流程包括本地开发环境、测试环境、生产环境等，除了本地开发环境和测试环境外，其他环境可统称为**服务器环境**。服务器环境的 `NODE_ENV` 应该为 `production`。而且 npm 也会使用这个变量，在应用部署时，一般不会安装 devDependencies，所以这个值也应该为 `production`。
 
-很多 Node.js 应用会使用 `NODE_ENV` 来区分运行环境，但 `EGG_SERVER_ENV` 区分得更加精细。一般的项目开发流程包括本地开发环境、测试环境、生产环境等，除了本地开发环境和测试环境外，其他环境可统称为**服务器环境**，服务器环境的 `NODE_ENV` 应该为 `production`。而且 npm 也会使用这个变量，在应用部署的时候一般不会安装 devDependencies，所以这个值也应该为 `production`。
+框架默认支持的运行环境及映射关系（如果未指定 `EGG_SERVER_ENV`，会根据 `NODE_ENV` 来匹配）如下表所示：
 
-框架默认支持的运行环境及映射关系（如果未指定 `EGG_SERVER_ENV` 会根据 `NODE_ENV` 来匹配）
-
-| NODE_ENV   | EGG_SERVER_ENV | 说明         |
-| ---------- | -------------- | ------------ |
-|            | local          | 本地开发环境 |
-| test       | unittest       | 单元测试     |
-| production | prod           | 生产环境     |
+| `NODE_ENV`   | `EGG_SERVER_ENV` | 说明         |
+|--------------|------------------|--------------|
+| （不设置）   | local            | 本地开发环境 |
+| test         | unittest         | 单元测试     |
+| production   | prod             | 生产环境     |
 
 例如，当 `NODE_ENV` 为 `production` 而 `EGG_SERVER_ENV` 未指定时，框架会将 `EGG_SERVER_ENV` 设置成 `prod`。
-
 ## 自定义环境
 
-常规开发流程可能不仅仅只有以上几种环境，Egg 支持自定义环境来适应自己的开发流程。
+Egg 框架支持开发者根据实际需要自定义开发环境。
 
-比如，要为开发流程增加集成测试环境 SIT。将 `EGG_SERVER_ENV` 设置成 `sit`（并建议设置 `NODE_ENV = production`），启动时会加载 `config/config.sit.js`，运行环境变量 `app.config.env` 会被设置成 `sit`。
+假如你需要在开发流程中加入 SIT 集成测试环境，只需将环境变量 `EGG_SERVER_ENV` 设为 `sit`。同时，建议设置 `NODE_ENV` 为 `production`，这样在启动项目时，Egg 会加载 `config/config.sit.js` 配置文件，并将运行时环境的 `app.config.env` 设为 `sit`。
 
 ## 与 Koa 的区别
 
-在 Koa 中我们通过 `app.env` 来进行环境判断，`app.env` 默认的值是 `process.env.NODE_ENV`。但是在 Egg（和基于 Egg 的框架）中，配置统一都放置在 `app.config` 上，所以我们需要通过 `app.config.env` 来区分环境，`app.env` 不再使用。
+在 Koa 中，我们通过 `app.env` 来判断运行环境，其默认值为 `process.env.NODE_ENV`。然而在 Egg（及基于 Egg 的框架）中，配置统一放置于 `app.config`，因此需要通过 `app.config.env` 来区分环境。不再使用 `app.env`。

site/docs/basics/env.zh-CN.md

@@ -3,15 +3,15 @@ title: 框架扩展
 order: 11
 ---
 
-框架提供了多种扩展点扩展自身的功能：
+框架提供了多种扩展点，以扩展自身的功能：
 
 - Application
 - Context
 - Request
 - Response
 - Helper
 
-在开发中，我们既可以使用已有的扩展 API 来方便开发，也可以对以上对象进行自定义扩展，进一步加强框架的功能。
+在开发中，我们既可以使用已有的扩展 API 来方便开发，也可以对以上对象进行自定义扩展，以进一步加强框架的功能。
 
 ## Application
 
@@ -20,19 +20,23 @@ order: 11
 ### 访问方式
 
 - `ctx.app`
-- Controller，Middleware，Helper，Service 中都可以通过 `this.app` 访问到 Application 对象，例如 `this.app.config` 访问配置对象。
-- 在 `app.js` 中 `app` 对象会作为第一个参数注入到入口函数中
+  
+  `ctx.app` 提供了一种访问全局 `app` 对象的方式。
 
-  ```js
-  // app.js
-  module.exports = (app) => {
-    // 使用 app 对象
-  };
-  ```
+- Controller，Middleware，Helper，Service 中都可以通过 `this.app` 访问到 Application 对象。例如，通过 `this.app.config` 可以访问配置对象。
+
+- 在 `app.js` 中，`app` 对象会作为第一个参数注入到入口函数中。
+
+```js
+// app.js
+module.exports = app => {
+  // 使用 app 对象
+};
+```
 
 ### 扩展方式
 
-框架会把 `app/extend/application.js` 中定义的对象与 Koa Application 的 prototype 对象进行合并，在应用启动时会基于扩展后的 prototype 生成 `app` 对象。
+框架会将 `app/extend/application.js` 中定义的对象与 Koa Application 的 prototype 对象进行合并。在应用启动时会基于扩展后的 prototype 生成 `app` 对象。
 
 #### 方法扩展
 
@@ -49,31 +53,30 @@ module.exports = {
 
 #### 属性扩展
 
-一般来说属性的计算只需要进行一次，那么一定要实现缓存，否则在多次访问属性时会计算多次，这样会降低应用性能。
+通常，属性的计算只需执行一次。因此，需要实现缓存以免多次访问属性时重复计算，这会降低应用性能。
 
-推荐的方式是使用 Symbol + Getter 的模式。
+推荐使用 Symbol 加 Getter 的模式实现属性缓存。
 
-例如，增加一个 `app.bar` 属性 Getter：
+例如，我们增加一个 `app.bar` 属性的 Getter：
 
 ```js
 // app/extend/application.js
 const BAR = Symbol('Application#bar');
 
 module.exports = {
   get bar() {
-    // this 就是 app 对象，在其中可以调用 app 上的其他方法，或访问属性
+    // this 是 app 对象，在其中可以调用 app 上的其他方法，或访问属性
     if (!this[BAR]) {
-      // 实际情况肯定更复杂
+      // 实际情况比这更复杂
       this[BAR] = this.config.xx + this.config.yy;
     }
     return this[BAR];
   },
 };
 ```
-
 ## Context
 
-Context 指的是 Koa 的请求上下文，这是 **请求级别** 的对象，每次请求生成一个 Context 实例，通常我们也简写成 `ctx`。在所有的文档中，Context 和 `ctx` 都是指 Koa 的上下文对象。
+Context 指的是 Koa 的请求上下文，这是请求级别的对象，每次请求生成一个 Context 实例，通常我们也简写成 `ctx`。在所有的文档中，Context 和 `ctx` 都是指 Koa 的上下文对象。
 
 ### 访问方式
 
@@ -83,7 +86,7 @@ Context 指的是 Koa 的请求上下文，这是 **请求级别** 的对象，
 
 ### 扩展方式
 
-框架会把 `app/extend/context.js` 中定义的对象与 Koa Context 的 prototype 对象进行合并，在处理请求时会基于扩展后的 prototype 生成 ctx 对象。
+框架会将 `app/extend/context.js` 中定义的对象与 Koa Context 的 prototype 对象进行合并，在处理请求时会基于扩展后的 prototype 生成 ctx 对象。
 
 #### 方法扩展
 
@@ -94,13 +97,13 @@ Context 指的是 Koa 的请求上下文，这是 **请求级别** 的对象，
 module.exports = {
   foo(param) {
     // this 就是 ctx 对象，在其中可以调用 ctx 上的其他方法，或访问属性
-  },
+  }
 };
 ```
 
 #### 属性扩展
 
-一般来说属性的计算在同一次请求中只需要进行一次，那么一定要实现缓存，否则在同一次请求中多次访问属性时会计算多次，这样会降低应用性能。
+一般来说，属性的计算在同一次请求中只需要进行一次，那么一定要实现缓存，否则在同一次请求中多次访问属性时会计算多次，这样会降低应用性能。
 
 推荐的方式是使用 Symbol + Getter 的模式。
 
@@ -118,11 +121,10 @@ module.exports = {
       this[BAR] = this.get('x-bar');
     }
     return this[BAR];
-  },
+  }
 };
 ```
-
-## Request
+## Request 对象
 
 Request 对象和 Koa 的 Request 对象相同，是 **请求级别** 的对象，它提供了大量请求相关的属性和方法供使用。
 
@@ -132,13 +134,13 @@ Request 对象和 Koa 的 Request 对象相同，是 **请求级别** 的对象
 ctx.request;
 ```
 
-`ctx` 上的很多属性和方法都被代理到 `request` 对象上，对于这些属性和方法使用 `ctx` 和使用 `request` 去访问它们是等价的，例如 `ctx.url === ctx.request.url`。
+`ctx` 上的很多属性和方法都被代理到 `request` 对象上，对于这些属性和方法使用 `ctx` 和使用 `request` 访问它们是等价的，例如 `ctx.url === ctx.request.url`。
 
-Koa 内置的代理 `request` 的属性和方法列表：[Koa - Request aliases](http://koajs.com/#request-aliases)
+Koa 内置的代理 `request` 的属性和方法列表可参阅：[Koa - Request aliases](http://koajs.com/#request-aliases)。
 
 ### 扩展方式
 
-框架会把 `app/extend/request.js` 中定义的对象与内置 `request` 的 prototype 对象进行合并，在处理请求时会基于扩展后的 prototype 生成 `request` 对象。
+框架会将 `app/extend/request.js` 中定义的对象与内置 `request` 的 prototype 对象进行合并，在处理请求时会基于扩展后的 prototype 生成 `request` 对象。
 
 例如，增加一个 `request.foo` 属性 Getter：
 
@@ -153,23 +155,23 @@ module.exports = {
 
 ## Response
 
-Response 对象和 Koa 的 Response 对象相同，是 **请求级别** 的对象，它提供了大量响应相关的属性和方法供使用。
+Response 对象和 Koa 的 Response 对象相同，是 **请求级别** 的对象，提供了众多响应相关的属性和方法供使用。
 
 ### 访问方式
 
 ```js
 ctx.response;
 ```
 
-ctx 上的很多属性和方法都被代理到 `response` 对象上，对于这些属性和方法使用 `ctx` 和使用 `response` 去访问它们是等价的，例如 `ctx.status = 404` 和 `ctx.response.status = 404` 是等价的。
+`ctx` 上的许多属性和方法都代理到了 `response` 对象上，因此直接通过 `ctx` 访问这些属性和方法与通过 `response` 访问是等价的。例如，`ctx.status = 404` 和 `ctx.response.status = 404` 是等价的。
 
-Koa 内置的代理 `response` 的属性和方法列表：[Koa Response aliases](http://koajs.com/#response-aliases)
+参考 Koa 官方文档中列出的内置代理 `response` 的属性和方法列表：[Koa Response aliases](http://koajs.com/#response-aliases)。
 
 ### 扩展方式
 
-框架会把 `app/extend/response.js` 中定义的对象与内置 `response` 的 prototype 对象进行合并，在处理请求时会基于扩展后的 prototype 生成 `response` 对象。
+框架会将 `app/extend/response.js` 中定义的对象与内置 `response` 的 prototype 对象合并，在处理请求时基于扩展后的 prototype 生成 `response` 对象。
 
-例如，增加一个 `response.foo` 属性 setter：
+例如，要增加一个 `response.foo` 属性的 setter：
 
 ```js
 // app/extend/response.js
@@ -180,13 +182,13 @@ module.exports = {
 };
 ```
 
-就可以这样使用啦：`this.response.foo = 'bar';`
+现在可以这样使用：`this.response.foo = 'bar';`。
 
 ## Helper
 
 Helper 函数用来提供一些实用的 utility 函数。
 
-它的作用在于我们可以将一些常用的动作抽离在 helper.js 里面成为一个独立的函数，这样可以用 JavaScript 来写复杂的逻辑，避免逻辑分散各处。另外还有一个好处是 Helper 这样一个简单的函数，可以让我们更容易编写测试用例。
+它的作用在于我们可以将一些常用的动作抽离在 `helper.js` 里面成为一个独立的函数，这样可以用 JavaScript 来写复杂的逻辑，避免逻辑分散各处。另外还有一个好处是 Helper 这样一个简单的函数，可以让我们更容易编写测试用例。
 
 框架内置了一些常用的 Helper 函数。我们也可以编写自定义的 Helper 函数。
 
@@ -222,7 +224,7 @@ module.exports = {
 
 ## 按照环境进行扩展
 
-另外，还可以根据环境进行有选择的扩展，例如，只在 unittest 环境中提供 `mockXX()` 方法以便进行 mock 方便测试。
+在 `unittest` 环境中，你可以选择性地扩展应用程序。例如，只在 `unittest` 现场提供 `mockXX()` 方法，便于进行 mock 测试。
 
 ```js
 // app/extend/application.unittest.js
@@ -231,6 +233,4 @@ module.exports = {
 };
 ```
 
-这个文件只会在 unittest 环境加载。
-
-同理，对于 Application，Context，Request，Response，Helper 都可以使用这种方式针对某个环境进行扩展，更多参见[运行环境](./env.md)。
+这个文件只会在 `unittest` 环境加载。同理，Application、Context、Request、Response 和 Helper 都可以使用这种方式针对某个特定环境进行扩展。更多信息，请参阅[运行环境](./env.md)。

site/docs/basics/extend.zh-CN.md

@@ -9,7 +9,7 @@ order: 5
 
 ### 写法
 
-我们先来通过编写一个简单的 gzip 中间件，来看看中间件的写法。
+我们首先来通过编写一个简单的 gzip 中间件，了解中间件的写法。
 
 ```js
 // app/middleware/gzip.js
@@ -19,7 +19,7 @@ const zlib = require('zlib');
 async function gzip(ctx, next) {
   await next();
 
-  // 后续中间件执行完成后将响应体转换成 gzip
+  // 后续中间件执行完成后，将响应体转换成 gzip
   let body = ctx.body;
   if (!body) return;
   if (isJSON(body)) body = JSON.stringify(body);
@@ -36,12 +36,12 @@ async function gzip(ctx, next) {
 
 ### 配置
 
-一般来说中间件也会有自己的配置。在框架中，一个完整的中间件是包含了配置处理的。我们约定一个中间件是一个放置在 `app/middleware` 目录下的单独文件，它需要 exports 一个普通的 function，接受两个参数：
+一般来说，中间件也会有自己的配置。在框架中，一个完整的中间件包含了配置处理。我们约定一个中间件是一个放置于 `app/middleware` 目录下的单独文件。它需要 `exports` 一个普通的函数，接受两个参数：
 
-- options: 中间件的配置项，框架会将 `app.config[${middlewareName}]` 传递进来。
-- app: 当前应用 Application 的实例。
+- `options`：中间件的配置项，框架会将 `app.config[${middlewareName}]` 传递进来。
+- `app`：当前应用 `Application` 的实例。
 
-我们将上面的 gzip 中间件做一个简单的优化，让它支持指定只有当 body 大于配置的 threshold 时才进行 gzip 压缩，我们要在 `app/middleware` 目录下新建一个文件 `gzip.js`
+下面我们对上文中的 gzip 中间件做一个简单的优化，使其支持指定只有当体积大于配置的 `threshold` 时才进行 gzip 压缩。我们在 `app/middleware` 目录下新建 `gzip.js` 文件。
 
 ```js
 // app/middleware/gzip.js
@@ -52,7 +52,7 @@ module.exports = (options) => {
   return async function gzip(ctx, next) {
     await next();
 
-    // 后续中间件执行完成后将响应体转换成 gzip
+    // 后续中间件执行完成后，将响应体转换成 gzip
     let body = ctx.body;
     if (!body) return;
 
@@ -69,7 +69,6 @@ module.exports = (options) => {
   };
 };
 ```
-
 ## 使用中间件
 
 中间件编写完成后，我们还需要手动挂载，支持以下方式：
@@ -87,8 +86,8 @@ module.exports = {
 
   // 配置 gzip 中间件的配置
   gzip: {
-    threshold: 1024, // 小于 1k 的响应体不压缩
-  },
+    threshold: 1024 // 小于 1k 的响应体不压缩
+  }
 };
 ```
 
@@ -100,14 +99,14 @@ module.exports = {
 
 ```js
 // app.js
-module.exports = (app) => {
+module.exports = app => {
   // 在中间件最前面统计请求时间
   app.config.coreMiddleware.unshift('report');
 };
 
 // app/middleware/report.js
 module.exports = () => {
-  return async function (ctx, next) {
+  return async function(ctx, next) {
     const startTime = Date.now();
     await next();
     // 上报请求时间
@@ -118,21 +117,20 @@ module.exports = () => {
 
 应用层定义的中间件（`app.config.appMiddleware`）和框架默认中间件（`app.config.coreMiddleware`）都会被加载器加载，并挂载到 `app.middleware` 上。
 
-### router 中使用中间件
+### 在 router 中使用中间件
 
 以上两种方式配置的中间件是全局的，会处理每一次请求。
 如果你只想针对单个路由生效，可以直接在 `app/router.js` 中实例化和挂载，如下：
 
 ```js
-module.exports = (app) => {
+module.exports = app => {
   const gzip = app.middleware.gzip({ threshold: 1024 });
   app.router.get('/needgzip', gzip, app.controller.handler);
 };
 ```
-
 ## 框架默认中间件
 
-除了应用层加载中间件之外，框架自身和其他的插件也会加载许多中间件。所有的这些自带中间件的配置项都通过在配置中修改中间件同名配置项进行修改，例如[框架自带的中间件](https://github.com/eggjs/egg/tree/master/app/middleware)中有一个 bodyParser 中间件（框架的加载器会将文件名中的各种分隔符都修改成驼峰形式的变量名），我们想要修改 bodyParser 的配置，只需要在 `config/config.default.js` 中编写
+除了应用层加载中间件之外，框架自身和其他插件也会加载许多中间件。所有这些自带中间件的配置项都可以通过修改配置文件中的同名配置项来进行更改。例如，框架自带的中间件列表中有一个名为 `bodyParser` 的中间件（框架的加载器会将文件名中的分隔符都转换为驼峰形式的变量名）。如果我们想要修改 `bodyParser` 的配置，只需要在 `config/config.default.js` 中编写如下内容：
 
 ```js
 module.exports = {
@@ -142,19 +140,18 @@ module.exports = {
 };
 ```
 
-**注意：框架和插件加载的中间件会在应用层配置的中间件之前，框架默认中间件不能被应用层中间件覆盖，如果应用层有自定义同名中间件，在启动时会报错。**
-
+**注意：框架和插件加载的中间件会在应用层配置的中间件之前被加载。框架默认中间件不能被应用层中间件覆盖。如果应用层有自定义同名中间件，启动时将会报错。**
 ## 使用 Koa 的中间件
 
-在框架里面可以非常容易的引入 Koa 中间件生态。
+在框架里面可以非常容易地引入 Koa 中间件生态。
 
-以 [koa-compress](https://github.com/koajs/compress) 为例，在 Koa 中使用时：
+以 [`koa-compress`](https://github.com/koajs/compress) 为例，在 Koa 中使用时：
 
 ```js
 const koa = require('koa');
 const compress = require('koa-compress');
 
-const app = koa();
+const app = new koa();
 
 const options = { threshold: 2048 };
 app.use(compress(options));
@@ -164,7 +161,7 @@ app.use(compress(options));
 
 ```js
 // app/middleware/compress.js
-// koa-compress 暴露的接口(`(options) => middleware`)和框架对中间件要求一致
+// koa-compress 暴露的接口（`(options) => middleware`）和框架对中间件要求一致
 module.exports = require('koa-compress');
 ```
 
@@ -196,18 +193,17 @@ module.exports = (options, app) => {
   return webpackMiddleware(options.compiler, options.others);
 };
 ```
-
 ## 通用配置
 
 无论是应用层加载的中间件还是框架自带中间件，都支持几个通用的配置项：
 
-- enable：控制中间件是否开启。
-- match：设置只有符合某些规则的请求才会经过这个中间件。
-- ignore：设置符合某些规则的请求不经过这个中间件。
+- `enable`：控制中间件是否开启。
+- `match`：设置只有符合某些规则的请求才会经过这个中间件。
+- `ignore`：设置符合某些规则的请求不经过这个中间件。
 
 ### enable
 
-如果我们的应用并不需要默认的 bodyParser 中间件来进行请求体的解析，此时我们可以通过配置 enable 为 false 来关闭它
+如果我们的应用并不需要默认的 `bodyParser` 中间件来进行请求体的解析，此时我们可以通过配置 `enable` 为 `false` 来关闭它。
 
 ```js
 module.exports = {
@@ -219,9 +215,9 @@ module.exports = {
 
 ### match 和 ignore
 
-match 和 ignore 支持的参数都一样，只是作用完全相反，match 和 ignore 不允许同时配置。
+`match` 和 `ignore` 支持的参数都一样，只是作用完全相反，`match` 和 `ignore` 不允许同时配置。
 
-如果我们想让 gzip 只针对 `/static` 前缀开头的 url 请求开启，我们可以配置 match 选项
+如果我们想让 `gzip` 只针对 `/static` 前缀开头的 url 请求开启，我们可以配置 `match` 选项。
 
 ```js
 module.exports = {
@@ -231,24 +227,22 @@ module.exports = {
 };
 ```
 
-match 和 ignore 支持多种类型的配置方式
+`match` 和 `ignore` 支持多种类型的配置方式：
 
-1. 字符串：当参数为字符串类型时，配置的是一个 url 的路径前缀，所有以配置的字符串作为前缀的 url 都会匹配上。
-   当然，你也可以直接使用字符串数组。
+1. 字符串：当参数为字符串类型时，配置的是一个 url 的路径前缀，所有以配置的字符串作为前缀的 url 都会匹配上。当然，你也可以直接使用字符串数组。
 2. 正则：当参数为正则时，直接匹配满足正则验证的 url 的路径。
-3. 函数：当参数为一个函数时，会将请求上下文传递给这个函数，最终取函数返回的结果（true/false）来判断是否匹配。
+3. 函数：当参数为一个函数时，会将请求上下文传递给这个函数，最终取函数返回的结果（`true`/`false`）来判断是否匹配。
 
 ```js
 module.exports = {
   gzip: {
     match(ctx) {
-      // 只有 ios 设备才开启
+      // 只有 iOS 设备才开启
       const reg = /iphone|ipad|ipod/i;
       return reg.test(ctx.get('user-agent'));
     },
   },
 };
 ```
 
-有关更多的 match 和 ignore 配置情况，详见
-[egg-path-matching](https://github.com/eggjs/egg-path-matching).
+有关更多的 `match` 和 `ignore` 配置情况，详见 [egg-path-matching](https://github.com/eggjs/egg-path-matching)。

site/docs/basics/middleware.zh-CN.md

@@ -3,16 +3,14 @@ title: 插件
 order: 9
 ---
 
-插件机制是我们框架的一大特色。它不但可以保证框架核心的足够精简、稳定、高效，还可以促进业务逻辑的复用，生态圈的形成。有人可能会问了
+插件机制是我们框架的一大特色。它不但可以保证框架核心的足够精简、稳定、高效，还可以促进业务逻辑的复用，生态圈的形成。有人可能会问了：
 
-- Koa 已经有了中间件的机制，为啥还要插件呢？
-- 中间件、插件、应用它们之间是什么关系，有什么区别？
-- 我该怎么使用一个插件？
+- Koa 已经有了中间件的机制，为什么还要插件呢？
+- 中间件、插件、应用之间是什么关系，它们之间有什么区别？
+- 我该如何使用一个插件？
 - 如何编写一个插件？
-- ...
-
-接下来我们就来逐一讨论
 
+接下来我们就来逐一讨论。
 ## 为什么要插件
 
 我们在使用 Koa 中间件过程中发现了下面一些问题：
@@ -25,28 +23,27 @@ order: 9
 
 ### 中间件、插件、应用的关系
 
-一个插件其实就是一个『迷你的应用』，和应用（app）几乎一样：
+一个插件其实就是一个“迷你的应用”，和应用（app）几乎一样：
 
 - 它包含了 [Service](./service.md)、[中间件](./middleware.md)、[配置](./config.md)、[框架扩展](./extend.md)等等。
 - 它没有独立的 [Router](./router.md) 和 [Controller](./controller.md)。
-- 它没有 `plugin.js`，只能声明跟其他插件的依赖，而**不能决定**其他插件的开启与否。
+- 它没有 `plugin.js`，只能声明和其他插件的依赖，而**不能决定**其他插件的开启与否。
 
 他们的关系是：
 
 - 应用可以直接引入 Koa 的中间件。
-- 当遇到上一节提到的场景时，则应用需引入插件。
+- 当遇到上一节提到的场景时，应用需引入插件。
 - 插件本身可以包含中间件。
 - 多个插件可以包装为一个[上层框架](../advanced/framework.md)。
-
 ## 使用插件
 
-插件一般通过 npm 模块的方式进行复用：
+插件通常通过 npm 模块的方式进行复用：
 
 ```bash
 $ npm i egg-mysql --save
 ```
 
-**注意：我们建议通过 `^` 的方式引入依赖，并且强烈不建议锁定版本。**
+**注意：我们推荐通过 `^` 的方式引入依赖，并且强烈不建议锁定版本。**
 
 ```json
 {
@@ -56,7 +53,7 @@ $ npm i egg-mysql --save
 }
 ```
 
-然后需要在应用或框架的 `config/plugin.js` 中声明：
+接着，需要在应用或框架的 `config/plugin.js` 中声明：
 
 ```js
 // config/plugin.js
@@ -67,7 +64,7 @@ exports.mysql = {
 };
 ```
 
-就可以直接使用插件提供的功能：
+这样就可以直接使用插件提供的功能：
 
 ```js
 app.mysql.query(sql, values);
@@ -79,23 +76,23 @@ app.mysql.query(sql, values);
 
 - `{Boolean} enable` - 是否开启此插件，默认为 true
 - `{String} package` - `npm` 模块名称，通过 `npm` 模块形式引入插件
-- `{String} path` - 插件绝对路径，跟 package 配置互斥
-- `{Array} env` - 只有在指定运行环境才能开启，会覆盖插件自身 `package.json` 中的配置
+- `{String} path` - 插件绝对路径，与 package 配置互斥
+- `{Array} env` - 只有在指定运行环境才能开启，会覆盖该插件自身 `package.json` 中的配置
 
 ### 开启和关闭
 
-在上层框架内部内置的插件，应用在使用时就不用配置 package 或者 path，只需要指定 enable 与否：
+在上层框架内置的插件，应用在使用时，可以不配置 package 或者 path，只需指定 enable 即可：
 
 ```js
-// 对于内置插件，可以用下面的简洁方式开启或关闭
+// 对于内置插件，可采用以下简洁方式开启或关闭
 exports.onerror = false;
 ```
 
 ### 根据环境配置
 
-同时，我们还支持 `plugin.{env}.js` 这种模式，会根据[运行环境](../basics/env.md)加载插件配置。
+同时，我们还支持 `plugin.{env}.js` 的模式，会根据[运行环境](../basics/env.md)加载插件配置。
 
-比如定义了一个开发环境使用的插件 `egg-dev`，只希望在本地环境加载，可以安装到 `devDependencies`。
+比如，如果定义了一个只在开发环境使用的插件 `egg-dev`，希望只在本地环境加载，可以将其安装到 `devDependencies` 中。
 
 ```js
 // npm i egg-dev --save-dev
@@ -107,7 +104,7 @@ exports.onerror = false;
 }
 ```
 
-然后在 `plugin.local.js` 中声明：
+接下来，在 `plugin.local.js` 中声明：
 
 ```js
 // config/plugin.local.js
@@ -117,18 +114,18 @@ exports.dev = {
 };
 ```
 
-这样在生产环境可以 `npm i --production` 不需要下载 `egg-dev` 的包了。
+这样，在生产环境下执行 `npm i --production` 时，就不需要下载 `egg-dev` 包了。
 
 **注意:**
 
-- 不存在 `plugin.default.js`
-- **只能在应用层使用，在框架层请勿使用。**
+- `plugin.default.js` 不存在 
+- **只能在应用层使用，框架层请勿使用。**
 
 ### package 和 path
 
 - `package` 是 `npm` 方式引入，也是最常见的引入方式
-- `path` 是绝对路径引入，如应用内部抽了一个插件，但还没达到开源发布独立 `npm` 的阶段，或者是应用自己覆盖了框架的一些插件
-- 关于这两种方式的使用场景，可以参见[渐进式开发](../intro/progressive.md)。
+- `path` 是绝对路径引入，例如应用内部提取了一个插件，但尚未发布至 npm；或者是应用自行改写了框架的某些插件
+- 关于这两种方式的使用场景，可参见[渐进式开发](../intro/progressive.md)文档。
 
 ```js
 // config/plugin.js
@@ -138,10 +135,9 @@ exports.mysql = {
   path: path.join(__dirname, '../lib/plugin/egg-mysql'),
 };
 ```
-
 ## 插件配置
 
-插件一般会包含自己的默认配置，应用开发者可以在 `config.default.js` 覆盖对应的配置：
+插件一般会包含自己的默认配置。应用开发者可以在 `config.default.js` 中覆盖对应的配置：
 
 ```js
 // config/config.default.js
@@ -151,13 +147,12 @@ exports.mysql = {
     port: '3306',
     user: 'test_user',
     password: 'test_password',
-    database: 'test',
-  },
+    database: 'test'
+  }
 };
 ```
 
-具体合并规则可以参见[配置](./config.md)。
-
+具体的合并规则可以参见[配置](./config.md)。
 ## 插件列表
 
 - 框架默认内置了企业级应用[常用的插件](https://eggjs.org/zh-cn/plugins/)：
@@ -173,7 +168,7 @@ exports.mysql = {
   - [static](https://github.com/eggjs/egg-static) 静态服务器
   - [jsonp](https://github.com/eggjs/egg-jsonp) jsonp 支持
   - [view](https://github.com/eggjs/egg-view) 模板引擎
-- 更多社区的插件可以 GitHub 搜索 [egg-plugin](https://github.com/topics/egg-plugin)。
+- 更多社区的插件可以在 GitHub 上搜索 [egg-plugin](https://github.com/topics/egg-plugin)。
 
 ## 如何开发一个插件
 

site/docs/basics/objects.zh-CN.md

@@ -3,11 +3,9 @@ title: 路由（Router）
 order: 6
 ---
 
-Router 主要用来描述请求 URL 和具体承担执行动作的 Controller 的对应关系，
-框架约定了 `app/router.js` 文件用于统一所有路由规则。
-
-通过统一的配置，我们可以避免路由规则逻辑散落在多个地方，从而出现未知的冲突，集中在一起我们可以更方便的来查看全局的路由规则。
+Router 主要用来描述请求 URL 和具体承担执行动作的 Controller 的对应关系，框架约定了 `app/router.js` 文件用于统一所有路由规则。
 
+通过统一的配置，我们可以避免路由规则逻辑散落在多个地方，从而出现未知的冲突。集中在一起，我们可以更方便地来查看全局的路由规则。
 ## 如何定义 Router
 
 - `app/router.js` 里面定义 URL 路由规则
@@ -35,7 +33,6 @@ class UserController extends Controller {
 ```
 
 这样就完成了一个最简单的 Router 定义，当用户执行 `GET /user/123`，`user.js` 这个里面的 info 方法就会执行。
-
 ## Router 详细定义说明
 
 下面是路由的完整定义，参数可以根据场景的不同，自由选择：
@@ -47,37 +44,37 @@ router.verb('path-match', middleware1, ..., middlewareN, app.controller.action);
 router.verb('router-name', 'path-match', middleware1, ..., middlewareN, app.controller.action);
 ```
 
-路由完整定义主要包括 5 个主要部分:
-
-- verb - 用户触发动作，支持 get，post 等所有 HTTP 方法，后面会通过示例详细说明。
-  - router.head - HEAD
-  - router.options - OPTIONS
-  - router.get - GET
-  - router.put - PUT
-  - router.post - POST
-  - router.patch - PATCH
-  - router.delete - DELETE
-  - router.del - 由于 delete 是一个保留字，所以提供了一个 delete 方法的别名。
-  - router.redirect - 可以对 URL 进行重定向处理，比如我们最经常使用的可以把用户访问的根目录路由到某个主页。
-- router-name 给路由设定一个别名，可以通过 Helper 提供的辅助函数 `pathFor` 和 `urlFor` 来生成 URL。(可选)
-- path-match - 路由 URL 路径。
-- middleware1 - 在 Router 里面可以配置多个 Middleware。(可选)
-- controller - 指定路由映射到的具体的 controller 上，controller 可以有两种写法：
-  - `app.controller.user.fetch` - 直接指定一个具体的 controller
-  - `'user.fetch'` - 可以简写为字符串形式
+路由的完整定义主要包括以下五个主要部分：
+
+- `verb`：用户触发动作，支持 get、post 等所有 HTTP 方法，后面会通过示例详细说明。
+  - `router.head`：HEAD
+  - `router.options`：OPTIONS
+  - `router.get`：GET
+  - `router.put`：PUT
+  - `router.post`：POST
+  - `router.patch`：PATCH
+  - `router.delete`：DELETE
+  - `router.del`：由于 delete 是一个保留字，所以提供了一个 delete 方法的别名。
+  - `router.redirect`：可以对 URL 进行重定向处理，比如我们最经常使用的可以把用户访问的根目录路由到某个主页。
+- `router-name`：给路由设定一个别名，可以通过 Helper 提供的辅助函数 `pathFor` 和 `urlFor` 来生成 URL。（可选）
+- `path-match`：路由 URL 路径。
+- `middlewareN`：在 Router 里面可以配置多个 Middleware。（可选）
+- `controller`：指定路由映射到的具体 controller 上，controller 可以有两种写法：
+  - `app.controller.user.fetch`：直接指定一个具体的 controller。
+  - `'user.fetch'`：可以简写为字符串形式。
 
 ### 注意事项
 
-- 在 Router 定义中， 可以支持多个 Middleware 串联执行
+- 在 Router 定义中，可以支持多个 Middleware 串联执行。
 - Controller 必须定义在 `app/controller` 目录中。
-- 一个文件里面也可以包含多个 Controller 定义，在定义路由的时候，可以通过 `${fileName}.${functionName}` 的方式指定对应的 Controller。
-- Controller 支持子目录，在定义路由的时候，可以通过 `${directoryName}.${fileName}.${functionName}` 的方式指定对应的 Controller。
+- 一个文件里面也可以包含多个 Controller 定义，在定义路由时，可以通过 `${fileName}.${functionName}` 的方式指定对应的 Controller。
+- Controller 支持子目录，在定义路由时，可以通过 `${directoryName}.${fileName}.${functionName}` 的方式指定对应的 Controller。
 
-下面是一些路由定义的方式：
+以下是一些路由定义的方式：
 
 ```js
 // app/router.js
-module.exports = (app) => {
+module.exports = app => {
   const { router, controller } = app;
   router.get('/home', controller.home);
   router.get('/user/:id', controller.user.page);
@@ -89,20 +86,18 @@ module.exports = (app) => {
 
 ### RESTful 风格的 URL 定义
 
-如果想通过 RESTful 的方式来定义路由，
-我们提供了 `app.router.resources('routerName', 'pathMatch', controller)` 快速在一个路径上生成 [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) 路由结构。
+如果想用 RESTful 的方式定义路由，我们提供了 `app.router.resources('routerName', 'pathMatch', controller)` 方法，快速在一个路径上生成 [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) 路由结构。
 
 ```js
 // app/router.js
-module.exports = (app) => {
+module.exports = app => {
   const { router, controller } = app;
   router.resources('posts', '/api/posts', controller.posts);
   router.resources('users', '/api/v1/users', controller.v1.users); // app/controller/v1/users.js
 };
 ```
 
-上面代码就在 `/posts` 路径上部署了一组 CRUD 路径结构，对应的 Controller 为 `app/controller/posts.js` 接下来，
-你只需要在 `posts.js` 里面实现对应的函数就可以了。
+上述代码就在 `/posts` 路径上部署了一组 CRUD 路径结构，对应的 Controller 为 `app/controller/posts.js`。接下来，只需在 `posts.js` 里面实现对应的函数即可。
 
 | Method | Path            | Route Name | Controller.Action             |
 | ------ | --------------- | ---------- | ----------------------------- |
@@ -131,11 +126,10 @@ exports.update = async () => {};
 exports.destroy = async () => {};
 ```
 
-如果我们不需要其中的某几个方法，可以不用在 `posts.js` 里面实现，这样对应 URL 路径也不会注册到 Router。
-
+如果我们不需要其中的某些方法，可以省略在 `posts.js` 里面的实现，这样对应的 URL 路径也不会注册到 Router 中。
 ## router 实战
 
-下面通过更多实际的例子，来说明 router 的用法。
+下面通过更多实际的例子，来说明 `router` 的用法。
 
 ### 参数获取
 
@@ -173,7 +167,7 @@ exports.info = async (ctx) => {
 
 #### 复杂参数的获取
 
-路由里面也支持定义正则，可以更加灵活的获取参数：
+路由里面也支持定义正则，可以更加灵活地获取参数：
 
 ```js
 // app/router.js
@@ -186,8 +180,8 @@ module.exports = (app) => {
 
 // app/controller/package.js
 exports.detail = async (ctx) => {
-  // 如果请求 URL 被正则匹配， 可以按照捕获分组的顺序，从 ctx.params 中获取。
-  // 按照下面的用户请求，`ctx.params[0]` 的 内容就是 `egg/1.0.0`
+  // 如果请求 URL 被正则匹配，可以按照捕获分组的顺序，从 ctx.params 中获取。
+  // 按照下面的用户请求，`ctx.params[0]` 的内容就是 `egg/1.0.0`
   ctx.body = `package:${ctx.params[0]}`;
 };
 
@@ -213,17 +207,15 @@ exports.post = async (ctx) => {
 
 > 附：
 
-> 这里直接发起 POST 请求会**报错**：'secret is missing'。错误信息来自 [koa-csrf/index.js#L69](https://github.com/koajs/csrf/blob/2.5.0/index.js#L69) 。
-
-> **原因**：框架内部针对表单 POST 请求均会验证 CSRF 的值，因此我们在表单提交时，请带上 CSRF key 进行提交，可参考[安全威胁 csrf 的防范](https://eggjs.org/zh-cn/core/security.html#安全威胁csrf的防范)
+> 这里直接发起 POST 请求会**报错**：'secret is missing'。错误信息来源于 [koa-csrf/index.js#L69](https://github.com/koajs/csrf/blob/2.5.0/index.js#L69)。
 
-> **注意**：上面的校验是因为框架中内置了安全插件 [egg-security](https://github.com/eggjs/egg-security)，提供了一些默认的安全实践，并且框架的安全插件是默认开启的，如果需要关闭其中一些安全防范，直接设置该项的 enable 属性为 false 即可。
+> **原因**：框架内部针对表单 POST 请求均会验证 CSRF 的值，因此我们在表单提交时，需要带上 CSRF key 进行提交。具体可参考[安全威胁 CSRF 的防范](https://eggjs.org/zh-cn/core/security.html#安全威胁csrf的防范)。
 
-> 「除非清楚的确认后果，否则不建议擅自关闭安全插件提供的功能。」
+> **注意**：上述校验是因为框架中内置了安全插件 [egg-security](https://github.com/eggjs/egg-security)，提供了一些默认的安全实践，并且框架的安全插件默认是开启的。如果需要关闭一些安全防范，直接设置相应选项的 `enable` 属性为 `false` 即可。
 
-> 这里在写例子的话可临时在 `config/config.default.js` 中设置
+> 虽然不推荐，但如果确实需要关闭某些安全功能，可以在 `config/config.default.js` 中设置以下代码：
 
-```
+```javascript
 exports.security = {
   csrf: false
 };
@@ -303,7 +295,7 @@ exports.index = async (ctx) => {
 ### 中间件的使用
 
 如果我们想把用户某一类请求的参数都大写，可以通过中间件来实现。
-这里我们只是简单说明下如何使用中间件，更多请查看 [中间件](./middleware.md)。
+这里我们仅简单说明如何使用中间件，更多信息请参考[中间件](./middleware.md)。
 
 ```js
 // app/controller/search.js
@@ -325,7 +317,7 @@ module.exports = (app) => {
     's',
     '/search',
     app.middleware.uppercase(),
-    app.controller.search,
+    app.controller.search.index,
   );
 };
 
@@ -334,9 +326,9 @@ module.exports = (app) => {
 
 ### 太多路由映射？
 
-如上所述，我们并不建议把路由规则逻辑散落在多个地方，会给排查问题带来困扰。
+如上所述，我们不建议在多个地方分散路由规则，这可能会导致问题排查困难。
 
-若确实有需求，可以如下拆分：
+如果确实存在需求，可以采用如下方法拆分：
 
 ```js
 // app/router.js
@@ -358,4 +350,4 @@ module.exports = (app) => {
 };
 ```
 
-也可直接使用 [egg-router-plus](https://github.com/eggjs/egg-router-plus)。
+如果需要更好的路由组织方式，也可以直接使用 [egg-router-plus](https://github.com/eggjs/egg-router-plus)。

site/docs/basics/plugin.zh-CN.md

@@ -6,16 +6,15 @@ order: 10
 虽然我们通过框架开发的 HTTP Server 是请求响应模型的，但是仍然还会有许多场景需要执行一些定时任务，例如：
 
 1. 定时上报应用状态。
-1. 定时从远程接口更新本地缓存。
-1. 定时进行文件切割、临时文件删除。
+2. 定时从远程接口更新本地缓存。
+3. 定时进行文件切割、临时文件删除。
 
 框架提供了一套机制来让定时任务的编写和维护更加优雅。
-
 ## 编写定时任务
 
 所有的定时任务都统一存放在 `app/schedule` 目录下，每一个文件都是一个独立的定时任务，可以配置定时任务的属性和要执行的方法。
 
-一个简单的例子，我们定义一个更新远程数据到内存缓存的定时任务，就可以在 `app/schedule` 目录下创建一个 `update_cache.js` 文件
+一个简单的例子，我们定义一个更新远程数据到内存缓存的定时任务，就可以在 `app/schedule` 目录下创建一个 `update_cache.js` 文件。
 
 ```js
 const Subscription = require('egg').Subscription;
@@ -41,7 +40,7 @@ class UpdateCache extends Subscription {
 module.exports = UpdateCache;
 ```
 
-还可以简写为
+还可以简写为：
 
 ```js
 module.exports = {
@@ -71,7 +70,7 @@ module.exports = {
 
 #### interval
 
-通过 `schedule.interval` 参数来配置定时任务的执行时机，定时任务将会每间隔指定的时间执行一次。interval 可以配置成
+通过 `schedule.interval` 参数来配置定时任务的执行时机，定时任务将会每间隔指定的时间执行一次。interval 可以配置成：
 
 - 数字类型，单位为毫秒数，例如 `5000`。
 - 字符类型，会通过 [ms](https://github.com/zeit/ms) 转换成毫秒数，例如 `5s`。
@@ -92,15 +91,15 @@ module.exports = {
 **注意：cron-parser 支持可选的秒（linux crontab 不支持）。**
 
 ```bash
-*    *    *    *    *    *
-┬    ┬    ┬    ┬    ┬    ┬
-│    │    │    │    │    |
-│    │    │    │    │    └ day of week (0 - 7) (0 or 7 is Sun)
-│    │    │    │    └───── month (1 - 12)
-│    │    │    └────────── day of month (1 - 31)
-│    │    └─────────────── hour (0 - 23)
-│    └──────────────────── minute (0 - 59)
-└───────────────────────── second (0 - 59, optional)
+* * * * * *
+┬ ┬ ┬ ┬ ┬ ┬
+│ │ │ │ │ │
+│ │ │ │ │ └─ 周日（0 - 7）（0 或 7 是周日）
+│ │ │ │ └─── 月份（1 - 12）
+│ │ │ └───── 日期（1 - 31）
+│ │ └─────── 小时（0 - 23）
+│ └───────── 分钟（0 - 59）
+└─────────── 秒（0 - 59，可选）
 ```
 
 ```js
@@ -121,10 +120,10 @@ module.exports = {
 
 ### 其他参数
 
-除了刚才介绍到的几个参数之外，定时任务还支持这些参数：
+除了上述介绍的几个参数，定时任务还支持以下参数：
 
-- `cronOptions`: 配置 cron 的时区等，参见 [cron-parser](https://github.com/harrisiirak/cron-parser#options) 文档
-- `immediate`：配置了该参数为 true 时，这个定时任务会在应用启动并 ready 后立刻执行一次这个定时任务。
+- `cronOptions`：配置 cron 的时区等，参见 [cron-parser](https://github.com/harrisiirak/cron-parser#options) 文档。
+- `immediate`：配置该参数为 true 时，这个定时任务会在应用启动并 ready 后立即执行一次这个定时任务。
 - `disable`：配置该参数为 true 时，这个定时任务不会被启动。
 - `env`：数组，仅在指定的环境下才启动该定时任务。
 
@@ -141,10 +140,9 @@ config.customLogger = {
   },
 };
 ```
-
 ### 动态配置定时任务
 
-有时候我们需要配置定时任务的参数。定时任务还有支持另一种写法：
+有时候，我们需要配置定时任务的参数。定时任务还可以支持另一种写法：
 
 ```js
 module.exports = (app) => {
@@ -165,11 +163,11 @@ module.exports = (app) => {
 
 ## 手动执行定时任务
 
-我们可以通过 `app.runSchedule(schedulePath)` 来运行一个定时任务。`app.runSchedule` 接受一个定时任务文件路径（`app/schedule` 目录下的相对路径或者完整的绝对路径），执行对应的定时任务，返回一个 Promise。
+我们可以通过 `app.runSchedule(schedulePath)` 来运行一个定时任务。`app.runSchedule` 接受一个定时任务文件路径（位于 `app/schedule` 目录下的相对路径或者完整的绝对路径），执行对应的定时任务，并返回一个 Promise 对象。
 
-有一些场景我们可能需要手动的执行定时任务，例如
+在以下场景中，我们可能需要手动执行定时任务：
 
-- 通过手动执行定时任务可以更优雅的编写对定时任务的单元测试。
+- 手动执行定时任务可以更优雅地编写定时任务的单元测试。
 
 ```js
 const mm = require('egg-mock');
@@ -183,12 +181,12 @@ it('should schedule work fine', async () => {
 });
 ```
 
-- 应用启动时，手动执行定时任务进行系统初始化，等初始化完毕后再启动应用。参见[应用启动自定义](./app-start.md)章节，我们可以在 `app.js` 中编写初始化逻辑。
+- 应用启动时，可以手动执行定时任务进行系统初始化。在初始化完毕后，再启动应用。具体可以参见[应用启动自定义](./app-start.md)章节。我们可以在 `app.js` 中编写初始化逻辑。
 
 ```js
 module.exports = (app) => {
   app.beforeStart(async () => {
-    // 保证应用启动监听端口前数据已经准备好了
+    // 保证应用启动监听端口前，数据已经准备好
     // 后续数据的更新由定时任务自动触发
     await app.runSchedule('update_cache');
   });
@@ -197,27 +195,27 @@ module.exports = (app) => {
 
 ## 扩展定时任务类型
 
-默认框架提供的定时任务只支持每台机器的单个进程执行和全部进程执行，有些情况下，我们的服务并不是单机部署的，这时候可能有一个集群的某一个进程执行一个定时任务的需求。
+虽然默认的框架提供的定时任务只支持单个进程执行和全部进程执行，但是在某些情况下，比如服务非单机部署时，我们可能需要集群中的某一个进程执行定时任务。
 
-框架并没有直接提供此功能，但开发者可以在上层框架自行扩展新的定时任务类型。
+虽然框架没有直接提供此功能，开发者可在上层框架中自行扩展新的定时任务类型。
 
-在 `agent.js` 中继承 `agent.ScheduleStrategy`，然后通过 `agent.schedule.use()` 注册即可：
+在 `agent.js` 中，继承 `agent.ScheduleStrategy`，然后通过 `agent.schedule.use()` 方法注册即可：
 
 ```js
 module.exports = (agent) => {
   class ClusterStrategy extends agent.ScheduleStrategy {
     start() {
-      // 订阅其他的分布式调度服务发送的消息，收到消息后让一个进程执行定时任务
-      // 用户在定时任务的 schedule 配置中来配置分布式调度的场景（scene）
+      // 订阅其他分布式调度服务发送的消息，收到消息后让一个进程执行定时任务
+      // 用户可以在定时任务的 schedule 属性中配置分布式调度的场景（scene）
       agent.mq.subscribe(this.schedule.scene, () => this.sendOne());
     }
   }
   agent.schedule.use('cluster', ClusterStrategy);
 };
 ```
 
-`ScheduleStrategy` 基类提供了：
+`ScheduleStrategy` 基类提供了以下方法：
 
-- `this.schedule` - 定时任务的属性，`disable` 是默认统一支持的，其他配置可以自行解析。
-- `this.sendOne(...args)` - 随机通知一个 worker 执行 task，`args` 会传递给 `subscribe(...args)` 或 `task(ctx, ...args)`。
-- `this.sendAll(...args)` - 通知所有的 worker 执行 task。
+- `this.schedule` - 定时任务的属性，所有任务默认支持的 `disable` 属性，以及其他自定义配置的解析。
+- `this.sendOne(...args)` - 随机通知某个 worker 执行 task，`args` 会传递给 `subscribe(...args)` 或 `task(ctx, ...args)` 方法。
+- `this.sendAll(...args)` - 通知所有的 worker 执行 task。

site/docs/basics/router.zh-CN.md

@@ -3,17 +3,15 @@ title: 服务（Service）
 order: 8
 ---
 
-简单来说，Service 就是在复杂业务场景下用于做业务逻辑封装的一个抽象层，提供这个抽象有以下几个好处：
-
-- 保持 Controller 中的逻辑更加简洁。
-- 保持业务逻辑的独立性，抽象出来的 Service 可以被多个 Controller 重复调用。
-- 将逻辑和展现分离，更容易编写测试用例，测试用例的编写具体可以查看[这里](../core/unittest.md)。
+简单来说，Service 就是在复杂业务场景下用于做业务逻辑封装的一个抽象层，它的提供具有以下几个优点：
 
+- 保持 Controller 中的逻辑更简洁。
+- 保持业务逻辑的独立性，抽象出的 Service 可以被多个 Controller 重复使用。
+- 分离逻辑和展示，这样更便于编写测试用例。具体的测试用例编写方法，可以参见[这里](../core/unittest.md)。
 ## 使用场景
 
-- 复杂数据的处理，比如要展现的信息需要从数据库获取，还要经过一定的规则计算，才能返回用户显示。或者计算完成后，更新到数据库。
-- 第三方服务的调用，比如 GitHub 信息获取等。
-
+- 数据处理：当需要展示的信息须从数据库获取，并经规则计算后才能显示给用户，或计算后需更新数据库时。
+- 第三方服务调用：例如获取 GitHub 信息等。
 ## 定义 Service
 
 ```js
@@ -24,7 +22,7 @@ class UserService extends Service {
   async find(uid) {
     const user = await this.ctx.db.query(
       'select * from user where uid = ?',
-      uid,
+      uid
     );
     return user;
   }
@@ -35,44 +33,41 @@ module.exports = UserService;
 
 ### 属性
 
-每一次用户请求，框架都会实例化对应的 Service 实例，由于它继承于 `egg.Service`，故拥有下列属性方便我们进行开发：
+每一次用户请求，框架都会实例化对应的 Service 实例。因为它继承自 `egg.Service`，所以我们拥有以下属性便于开发：
 
-- `this.ctx`: 当前请求的上下文 [Context](./extend.md#context) 对象的实例，通过它我们可以拿到框架封装好的处理当前请求的各种便捷属性和方法。
-- `this.app`: 当前应用 [Application](./extend.md#application) 对象的实例，通过它我们可以拿到框架提供的全局对象和方法。
-- `this.service`：应用定义的 [Service](./service.md)，通过它我们可以访问到其他业务层，等价于 `this.ctx.service` 。
-- `this.config`：应用运行时的[配置项](./config.md)。
-- `this.logger`：logger 对象，上面有四个方法（`debug`，`info`，`warn`，`error`），分别代表打印四个不同级别的日志，使用方法和效果与 [context logger](../core/logger.md#context-logger) 中介绍的一样，但是通过这个 logger 对象记录的日志，在日志前面会加上打印该日志的文件路径，以便快速定位日志打印位置。
+- `this.ctx`：当前请求的上下文 [Context](./extend.md#context) 对象实例。通过它，我们可以获取框架封装的处理当前请求的各种便捷属性和方法。
+- `this.app`：当前应用 [Application](./extend.md#application) 对象实例。通过它，我们可以访问框架提供的全局对象和方法。
+- `this.service`：应用定义的 [Service](./service.md)。通过它，我们可以访问到其他业务层，等同于 `this.ctx.service`。
+- `this.config`：应用运行时的 [配置项](./config.md)。
+- `this.logger`：logger 对象。它有四个方法（`debug`，`info`，`warn`，`error`），分别代表不同级别的日志。使用方法和效果与 [context logger](../core/logger.md#context-logger) 所述一致。但通过这个 logger 记录的日志，在日志前会加上文件路径，方便定位日志位置。
 
 ### Service ctx 详解
 
-为了可以获取用户请求的链路，我们在 Service 初始化中，注入了请求上下文, 用户在方法中可以直接通过 `this.ctx` 来获取上下文相关信息。关于上下文的具体详解可以参看 [Context](./extend.md#context),
-有了 ctx 我们可以拿到框架给我们封装的各种便捷属性和方法。比如我们可以用：
+为了能获取用户请求的链路，在 Service 初始化时，注入了请求上下文。用户可以通过 `this.ctx` 直接获取上下文相关信息。关于上下文的更多详细解释，请参考 [Context](./extend.md#context)。有了 `ctx`，我们可以：
 
-- `this.ctx.curl` 发起网络调用。
-- `this.ctx.service.otherService` 调用其他 Service。
-- `this.ctx.db` 发起数据库调用等， db 可能是其他插件提前挂载到 app 上的模块。
+- 使用 `this.ctx.curl` 发起网络调用。
+- 通过 `this.ctx.service.otherService` 调用其他 Service。
+- 调用 `this.ctx.db` 发起数据库操作，`db` 可能是插件预挂载到 app 上的模块。
 
 ### 注意事项
 
-- Service 文件必须放在 `app/service` 目录，可以支持多级目录，访问的时候可以通过目录名级联访问。
+- Service 文件必须放在 `app/service` 目录下，支持多级目录。可以通过目录名级联访问。
 
   ```js
+  // app/service/biz/user.js 对应到 ctx.service.biz.user
   app/service/biz/user.js => ctx.service.biz.user
+  // app/service/sync_user.js 对应到 ctx.service.syncUser
   app/service/sync_user.js => ctx.service.syncUser
+  // app/service/HackerNews.js 对应到 ctx.service.hackerNews
   app/service/HackerNews.js => ctx.service.hackerNews
   ```
 
-- 一个 Service 文件只能包含一个类， 这个类需要通过 `module.exports` 的方式返回。
-- Service 需要通过 Class 的方式定义，父类必须是 `egg.Service`。
-- Service 不是单例，是 **请求级别** 的对象，框架在每次请求中首次访问 `ctx.service.xx` 时延迟实例化，所以 Service 中可以通过 this.ctx 获取到当前请求的上下文。
-
-## 使用 Service
-
-下面就通过一个完整的例子，看看怎么使用 Service。
-
+- 一个 Service 文件仅包含一个类，该类需通过 `module.exports` 导出。
+- Service 应通过 Class 形式定义，且继承自 `egg.Service`。
+- Service 不是单例，它是请求级别的对象。框架在每次请求中初次访问 `ctx.service.xx` 时才进行实例化。因此，Service 中可以通过 `this.ctx` 获取当前请求的上下文。
 ```js
 // app/router.js
-module.exports = (app) => {
+module.exports = app => {
   app.router.get('/user/:id', app.controller.user.info);
 };
 
@@ -92,31 +87,31 @@ module.exports = UserController;
 const Service = require('egg').Service;
 class UserService extends Service {
   // 默认不需要提供构造函数。
-  // constructor(ctx) {
-  //   super(ctx); 如果需要在构造函数做一些处理，一定要有这句话，才能保证后面 `this.ctx`的使用。
-  //   // 就可以直接通过 this.ctx 获取 ctx 了
-  //   // 还可以直接通过 this.app 获取 app 了
-  // }
+  /* constructor(ctx) {
+       super(ctx); // 如果需要在构造函数做一些处理，一定要有这句话，才能保证后面 `this.ctx` 的使用。
+       // 就可以直接通过 this.ctx 获取 ctx 了
+       // 还可以直接通过 this.app 获取 app 了
+     } */
   async find(uid) {
-    // 假如 我们拿到用户 id 从数据库获取用户详细信息
+    // 假如我们拿到用户 id，从数据库获取用户详细信息
     const user = await this.ctx.db.query(
       'select * from user where uid = ?',
-      uid,
+      uid
     );
 
-    // 假定这里还有一些复杂的计算，然后返回需要的信息。
+    // 假定这里还有一些复杂的计算，然后返回需要的信息
     const picture = await this.getPicture(uid);
 
     return {
       name: user.user_name,
       age: user.age,
-      picture,
+      picture
     };
   }
 
   async getPicture(uid) {
     const result = await this.ctx.curl(`http://photoserver/uid=${uid}`, {
-      dataType: 'json',
+      dataType: 'json'
     });
     return result.data;
   }

site/docs/basics/schedule.zh-CN.md

@@ -8,36 +8,36 @@ order: 1
 ```bash
 egg-project
 ├── package.json
-├── app.js (可选)
-├── agent.js (可选)
+├── app.js（可选）
+├── agent.js（可选）
 ├── app
 |   ├── router.js
 │   ├── controller
-│   |   └── home.js
-│   ├── service (可选)
-│   |   └── user.js
-│   ├── middleware (可选)
-│   |   └── response_time.js
-│   ├── schedule (可选)
-│   |   └── my_task.js
-│   ├── public (可选)
-│   |   └── reset.css
-│   ├── view (可选)
-│   |   └── home.tpl
-│   └── extend (可选)
-│       ├── helper.js (可选)
-│       ├── request.js (可选)
-│       ├── response.js (可选)
-│       ├── context.js (可选)
-│       ├── application.js (可选)
-│       └── agent.js (可选)
+│   │   └── home.js
+│   ├── service（可选）
+│   │   └── user.js
+│   ├── middleware（可选）
+│   │   └── response_time.js
+│   ├── schedule（可选）
+│   │   └── my_task.js
+│   ├── public（可选）
+│   │   └── reset.css
+│   ├── view（可选）
+│   │   └── home.tpl
+│   └── extend（可选）
+│       ├── helper.js（可选）
+│       ├── request.js（可选）
+│       ├── response.js（可选）
+│       ├── context.js（可选）
+│       ├── application.js（可选）
+│       └── agent.js（可选）
 ├── config
 |   ├── plugin.js
 |   ├── config.default.js
 │   ├── config.prod.js
-|   ├── config.test.js (可选)
-|   ├── config.local.js (可选)
-|   └── config.unittest.js (可选)
+|   ├── config.test.js（可选）
+|   ├── config.local.js（可选）
+|   └── config.unittest.js（可选）
 └── test
     ├── middleware
     |   └── response_time.test.js
@@ -49,21 +49,22 @@ egg-project
 
 - `app/router.js` 用于配置 URL 路由规则，具体参见 [Router](./router.md)。
 - `app/controller/**` 用于解析用户的输入，处理后返回相应的结果，具体参见 [Controller](./controller.md)。
-- `app/service/**` 用于编写业务逻辑层，可选，建议使用，具体参见 [Service](./service.md)。
-- `app/middleware/**` 用于编写中间件，可选，具体参见 [Middleware](./middleware.md)。
-- `app/public/**` 用于放置静态资源，可选，具体参见内置插件 [egg-static](https://github.com/eggjs/egg-static)。
-- `app/extend/**` 用于框架的扩展，可选，具体参见[框架扩展](./extend.md)。
-- `config/config.{env}.js` 用于编写配置文件，具体参见[配置](./config.md)。
-- `config/plugin.js` 用于配置需要加载的插件，具体参见[插件](./plugin.md)。
-- `test/**` 用于单元测试，具体参见[单元测试](../core/unittest.md)。
-- `app.js` 和 `agent.js` 用于自定义启动时的初始化工作，可选，具体参见[启动自定义](./app-start.md)。关于`agent.js`的作用参见[Agent 机制](../core/cluster-and-ipc.md#agent-机制)。
+- `app/service/**` 用于编写业务逻辑层，建议使用，具体参见 [Service](./service.md)。
+- `app/middleware/**` 用于编写中间件，具体参见 [Middleware](./middleware.md)。
+- `app/public/**` 用于放置静态资源，具体参见内置插件 [egg-static](https://github.com/eggjs/egg-static)。
+- `app/extend/**` 用于框架的扩展，具体参见 [框架扩展](./extend.md)。
+- `config/config.{env}.js` 用于编写配置文件，具体参见 [配置](./config.md)。
+- `config/plugin.js` 用于配置需要加载的插件，具体参见 [插件](./plugin.md)。
+- `test/**` 用于单元测试，具体参见 [单元测试](../core/unittest.md)。
+- `app.js` 和 `agent.js` 用于自定义启动时的初始化工作，具体参见 [启动自定义](./app-start.md)。关于 `agent.js` 的作用，参见 [Agent 机制](../core/cluster-and-ipc.md#agent-机制)。
+
 
 由内置插件约定的目录：
 
-- `app/public/**` 用于放置静态资源，可选，具体参见内置插件 [egg-static](https://github.com/eggjs/egg-static)。
-- `app/schedule/**` 用于定时任务，可选，具体参见[定时任务](./schedule.md)。
+- `app/public/**` 用于放置静态资源，具体参见内置插件 [egg-static](https://github.com/eggjs/egg-static)。
+- `app/schedule/**` 用于定时任务，具体参见 [定时任务](./schedule.md)。
 
 **若需自定义自己的目录规范，参见 [Loader API](https://eggjs.org/zh-cn/advanced/loader.html)**
 
-- `app/view/**` 用于放置模板文件，可选，由模板插件约定，具体参见[模板渲染](../core/view.md)。
-- `app/model/**` 用于放置领域模型，可选，由领域类相关插件约定，如 [egg-sequelize](https://github.com/eggjs/egg-sequelize)。
+- `app/view/**` 用于放置模板文件，具体参见 [模板渲染](../core/view.md)。
+- `app/model/**` 用于放置领域模型，如 [`egg-sequelize`](https://github.com/eggjs/egg-sequelize) 等领域类相关插件。