Merge pull request #2 from SalakJS/docs/1

docs(middleware,router): 增加路由加载顺序说明

Author: wengeek

website/translated_docs/zh-CN/middleware.md

@@ -3,7 +3,7 @@ id: middleware
 title: 中间件
 ---
 
-Salak是基于Koa 2.0开发，所以Salak的中间件形式与Koa中间件一致。
+Salak 是基于 Koa 2.0 开发，所以 Salak 的中间件形式与 Koa 中间件一致。
 
 ## 编写中间件
 
@@ -26,9 +26,9 @@ module.export = async (ctx, next) => {
 }
 ```
 
-如果返回 async function，会加入到中间件执行队列中，否则会先执行mw(options, app)，然后将返回结果加入到中间件执行队列。
+如果返回 async function，会加入到中间件执行队列中，否则会先执行 mw(options, app)，然后将返回结果加入到中间件执行队列。
 
-接下来，我们以写简单的error中间件为例：
+接下来，我们以写简单的 error 中间件为例：
 
 ```javascript
 module.exports = ({ status = 500 } = {}, app) => {
@@ -51,26 +51,26 @@ module.exports = ({ status = 500 } = {}, app) => {
 
 #### 模块配置中使用
 
-通过配置middleware字段，中间件配置通过配置对应的key即可
+通过配置 middleware 字段，中间件配置通过配置对应的 key 即可
 
-middleware配置有两种写法：
+middleware 配置有两种写法：
 
-- 直接写中间件对应文件的名字，如error.js:
+- 直接写中间件对应文件的名字，如 error.js:
 
 ```javascript
+// common/config/default.js:
 module.exports = {
-  middleware: [
-    'error'
-  ],
+  middleware: ['error'],
   error: {
     status: 500
   }
 }
 ```
 
-- 写中间件名字，以及中间对应的位置，如果中间件通过npm安装，只需指定包名即可，如：
+- 写中间件名字，以及中间对应的位置，如果中间件通过 npm 安装，只需指定包名即可，如：
 
 ```javascript
+// common/config/default.js:
 module.exports = {
   middleware: [
     {
@@ -88,17 +88,24 @@ module.exports = {
 #### 控制器构造函数中使用
 
 ```javascript
-this.middleware('error', this.module, {
-  status: 503
-})
+// src/${module}/controller/${name}.js:
+constructor () {
+  this.middleware('error', this.module, {
+    status: 503
+  })
+}
+
 ```
 
 控制器构造函数还支持控制器内自定义中间件，如
 
 ```javascript
-this.middleware(async (ctx, next) => {
-  await next()
-})
+// src/${module}/controller/${name}.js:
+constructor () {
+  this.middleware(async (ctx, next) => {
+    await next()
+  })
+}
 ```
 
 ### 中间件查询原则
@@ -107,7 +114,7 @@ this.middleware(async (ctx, next) => {
 
 在控制器中，指定模块中间件，查询不到，会查询框架内建中间件
 
-### 使用Koa中间件
+### 使用 Koa 中间件
 
 以[koa-etag](https://github.com/koajs/etag)为例，在框架运行中加载这个中间件，只需要在配置文件中添加如下代码：
 
@@ -131,13 +138,13 @@ module.exports = {
 
 框架自带的中间件或应用层中间件，都支持如下配置：
 
-- `enable`: Boolean，控制中间件是否开启，默认为true
+- `enable`: Boolean，控制中间件是否开启，默认为 true
 - `match`: Regex|string|Array|Function，设置只有符合条件的请求才经过该中间件
 - `ignore`: Regex|string|Array|Function，设置符合某些规则的请求不经过该中间件
 
 ### enable
 
-如果我们需要禁用某个中间件，只需要将其设置为false即可。
+如果我们需要禁用某个中间件，只需要将其设置为 false 即可。
 
 ```javascript
 module.exports = {
@@ -149,9 +156,9 @@ module.exports = {
 
 ### match/ignore
 
-match和ignore参数一致，但作用相反，不允许同时配置。
+match 和 ignore 参数一致，但作用相反，不允许同时配置。
 
-如想让仅以/meta开头的请求使用meta中间件，配置如下：
+如想让仅以/meta 开头的请求使用 meta 中间件，配置如下：
 
 ```javascript
 module.exports = {
@@ -161,16 +168,16 @@ module.exports = {
 }
 ```
 
-match和ignore支持的参数如下：
+match 和 ignore 支持的参数如下：
 
-- `string`: 当参数为字符串时，配置的是URL前缀，也能配置成字符串数组；
+- `string`: 当参数为字符串时，配置的是 URL 前缀，也能配置成字符串数组；
 - `Regex`: 正则表达式，直接匹配路径是否符合条件；
-- `Function`: 允许传入函数，由用户控制具体的规则，参数为ctx，通过返回 true/false 来判断是否满足条件。
+- `Function`: 允许传入函数，由用户控制具体的规则，参数为 ctx，通过返回 true/false 来判断是否满足条件。
 
 ```javascript
 module.exports = {
   meta: {
-    match (ctx) {
+    match(ctx) {
       if (ctx.path.indexOf('meta') !== 0) {
         return true
       }
@@ -193,7 +200,7 @@ module.exports = {
 
 ### 禁用默认中间件
 
-在根模块配置中，将内置中间件enable设置为false即可。
+在根模块配置中，将内置中间件 enable 设置为 false 即可。
 
 如：
 
@@ -207,43 +214,43 @@ module.exports = {
 
 ### static
 
-静态资源渲染，采用koa-static
+静态资源渲染，采用 koa-static
 
 配置：
 
-- `root`: 默认为应用public
+- `root`: 默认为应用 public
 - `opts`: 同[koa-static opts](https://github.com/koajs/static#options)
 
 ### bodyParser
 
-采用了koa-bodyparser，默认支持json、form解析
+采用了 koa-bodyparser，默认支持 json、form 解析
 
 配置可参考[koa-bodyparser](https://github.com/koajs/bodyparser#options)
 
-**注：koa-bodyparser已经不包含multipart/form-data解析**
+**注：koa-bodyparser 已经不包含 multipart/form-data 解析**
 
 ### error
 
-error中间件，处理应用请求过程中报错
+error 中间件，处理应用请求过程中报错
 
 配置:
 
-- `status`: 状态码设置，默认为'auto'，表示根据出错状态来自动设置http响应状态码；否则为200状态码
-- `type`: 错误输出类型，可以为json或者html，无配置情况下，框架根据accept-type自动选择
+- `status`: 状态码设置，默认为'auto'，表示根据出错状态来自动设置 http 响应状态码；否则为 200 状态码
+- `type`: 错误输出类型，可以为 json 或者 html，无配置情况下，框架根据 accept-type 自动选择
 
 ### notFound
 
-notFound中间件，处理应用请求404错误
+notFound 中间件，处理应用请求 404 错误
 
 配置：
 
-- `type`: 输出类型，可以为json或html，无配置情况下，框架根据accept-type自动选择
-- `pageUrl`: 如设置，出现404时，则跳转至相应URL
+- `type`: 输出类型，可以为 json 或 html，无配置情况下，框架根据 accept-type 自动选择
+- `pageUrl`: 如设置，出现 404 时，则跳转至相应 URL
 - `notFoundHtml`: 定制错误页面
 
 ### siteFile
 
-siteFile中间件，用于配置网站文件
+siteFile 中间件，用于配置网站文件
 
 如：
 

website/translated_docs/zh-CN/router.md

@@ -57,6 +57,10 @@ module.exports = {
 - `defaultMethods: string|string[]`: 默认注册的HTTP Methods，默认为GET
 - `loadOrder: string[]`: Controller加载顺序，可指定加载模块哪些控制器以及相应的路由注册顺序
 
+## 路由匹配顺序
+在URL可以匹配多个路由的情况下，路由的选择默认是由对应actionXXX方法在controller中注册的先后顺序决定，与behavior或controller中Routes中配置顺序无关。使用loadOrder配置可以覆盖默认行为。
+
+
 ## 路由注册路径
 
 在框架启动时，会生成 `/runtime/router/definitions.json`，该文件包含了注册的所有路由，可以根据该文件来排查一些问题。