meta-api 0.0.4 → 0.0.6

data/docs//346/225/231/347/250/213.md

@@ -1,6 +1,6 @@
 # 教程
 
-现有的 Web API 框架并不关注文档的问题，文档往往是作为插件挂载到框架上的。但是，文档和业务实现并不需要割裂开，它们在很大程度上应该是耦合在一起的。比方说，某个接口我定义了参数如此，就该自动生成一致的文档向前端告知；同样，当我提供了文档是如此后，我的接口实现就改自动地约束为这样实现。
+现有的 Web API 框架并不关注文档的问题，文档往往是作为插件挂载到框架上的。但是，文档和业务实现并不需要割裂开，它们在很大程度上应该是耦合在一起的。比方说，某个接口我定义了参数如此，就该自动生成一致的文档向前端告知；同样，当我提供了文档是如此后，我的接口实现就该自动地约束为这样实现。
 
 Meta 框架天生就是将文档和实现统一起来的，并始终致力于此（如果真的有什么不一致或者不到位的地方，那只能说框架实现上尚有欠缺，并不能从思想上说本该如此）。Meta 框架与 Swagger 合作，致力于产生符合 Restful 和社区规范的文档格式。它提供了几乎完整的描述接口信息的宏命令，并且在描述接口的同时就能基本实现接口的一些约束，其中最重要的莫过于对参数和返回值的声明。
 
@@ -8,341 +8,483 @@ Meta 框架天生就是将文档和实现统一起来的，并始终致力于此
 
 在正式阅读本教程之前，有一些*准备工作*需要提前了解的。
 
-### 一些限制
+### 只接受 JSON
 
-在正式介绍框架能力之前，我先声明一下框架的约束。设定这些约束，主要是因为框架开发尚处于初期阶段，而且精力有限，因此将框架的完成度限定在更小的范围内。
+**只接受格式为 `application/json` 的请求体参数，并且响应实体的格式一律为 `application/json`.**
 
-1. **只接受格式为 `application/json` 的请求参数，并且响应实体的格式一律为 `application/json`.**
-   
-   这在当前的环境下并不算太大的限制，如果你是致力于新项目的开发的话。但是，如果你处理旧项目，并且要求格式为 `application/json` 之外的格式，如 `application/xml`，则框架目前是无能为力的。
-   
-   这中限制只包括请求参数的实体，诸如路径里的参数、或 query 中的参数依然可用，不受该限制。
+这在当前的环境下并不算太大的限制，如果你是致力于新项目的开发的话。但是，如果你处理旧项目，并且要求格式为 `application/json` 之外的格式，如 `application/xml`，则框架目前是不能自动处理的。
 
-2. **由于只能接受 `application/json` 的请求格式，因此你无法使用传统的表单上传方式。**
-   
-   表单上传有它特有的格式名，为 `multipart/form-data`. 因此，用框架提供的行为无法完成表单上传的格式。这并不是说无法完成表单上传的功能，你可能需要处理原生的 `Request` 对象（它是 Rack 架构提供的一个对象，参考 [Rack::Request](https://www.rubydoc.info/gems/rack/Rack/Request)）。同样的，你如果要返回 `application/json` 之外的格式，你需要手动地处理原生的 `Response` 对象（同样也是 Rack 架构提供的一个对象，参考 [Rack::Response](https://www.rubydoc.info/gems/rack/Rack/Response)）。
+这种限制只存在于通过 `params` 宏和 `status` 宏设定了请求体和响应体格式的情况。如果你没有用到这两个宏，那么你还是可以自由定义请求体和响应体的格式，只不过缺少了文档化的支持。自由实现需要用到 [`Rack::Request`](https://www.rubydoc.info/gems/rack/Rack/Request) 类和 [`Rack::Response`](https://www.rubydoc.info/gems/rack/Rack/Response) 类提供的方法，这是 Rack 架构提供的两个包装类，用于简化 HTTP 请求和响应操作。
 
 ### 教程脉络
 
-首先，你将了解定义路由的全部知识。你从其他框架学习的经验也同样适用于本框架，如嵌套路由、before/after 钩子、异常拦截等、以及模块共享和复用等。
+首先，你将学到定义路由的全部知识。换句话说，你该如何具体地*描述*一个接口。一般来说，我们需要描述接口的标题、详述、标签、参数和返回值。
 
-然后，你将了解路由的内部如何定义。换句话说，你该如何具体地*描述*一个接口。一般来说，我们需要描述接口的标题、详述、标签、参数和返回值。
+然后，你将学到命名空间的概念。命名空间用来组织接口的层级结构，并且会用到诸如如路由嵌套、before/after 钩子、异常拦截等概念。
 
-接下来，我们将深入参数和返回值的定义。虽然说前面已经提到参数和返回值的知识，但仅覆盖最简单同时也是最常用的场景。参数和返回值的知识实在是太大了，有必要专门划出一个章节来介绍它。这里提一下，参数和返回值在 Meta 框架里都统一为一个叫做实体的概念，因此你只需要学会定义一种就能够同时定义两者了。
+从命名空间引申出的模块的概念也很重要。模块本身也是一个命名空间，命名空间用到的功能都可以用在模块中。除此之外，模块还用来组织大型应用的结构。最后，模块本身也是一个 Rack 应用，可以直接放在服务器下运行。
 
-最后，将是一个生成文档的方法。虽然它很简单，仅仅是一个方法，但它如此重要以至于我不得不专门划出一个章节来强调它的重要性。说实话将这块内容放在最后我有点不太满意，它是如此重要，开篇就该提到。
+接下来是重点，我们将深入参数和返回值的定义。虽然说前面已经提到参数和返回值的知识，但仅覆盖最简单同时也是最常用的场景。参数和返回值的知识实在是太大了，有必要专门划出一个章节来介绍它。这里提一下，参数和返回值在 Meta 框架里都统一为一个叫做实体的概念，因此你只需要学会定义一种就能够同时定义两者了。
 
-## 模块和路由定义
+最后，将是一个生成文档的方法。虽然它很简单，仅仅是一个方法，但它如此重要以至于我不得不专门划出一个章节来强调它的重要性。
 
-*（我抛弃了 Rack 和中间件的知识，如果你知道它将更好了）*
+文章的最后是特殊用法举例。说实话，我还没想好把它放哪，但它确实列举了几个比较常见的场景。
 
-在 Meta 中，`Meta::Application` 类用来定义一个模块。一个模块同时也是一个应用，将它挂载在 Rack 下可以直接作为一个服务运行。我将它称为模块主要是因为它可以复用（后面你将了解到使用 `apply` 方法复用一个模块）。
+### 继承和宏定义
 
-我们先看一下最简单的 `Meta::Application` 实例：
+在使用 Meta 框架提供的组件时，我们往往先要继承一个类，然后直接在类定义中使用宏命令。所谓的宏命令其实就是一个 Ruby 方法，只不过在 DSL 术语中我们将它称为“宏”。
+
+例如，定义一个 API，我们继承的是 `Meta::Application` 类，然后在类中使用 `route` 宏定义路由：
 
 ```ruby
 class DemoApp < Meta::Application
-  get do
-    title '应用的根路径'
-    action do
-      response.body = ["Hello, world!"]
-    end
+  route '/foo', :get do
+    # ... 具体的宏定义
   end
 end
 ```
 
-*将它挂载在 Rack 下并访问 `http://localhost:9292` 你将看到效果。*
+再比如继承 `Meta::Entity` 定义一个实体，实体内使用 `property` 宏定义属性：
 
-这里，我们只是用 `get` 方法简单地定义了一个 `get /`  路由，并定义了该路由下的标题和实现。该实现没有用到 Meta 框架提供的参数和返回值的概念，只是简单地操纵原生 Rack Response 对象返回一个纯文本格式。
+```ruby
+class UserEntity < Meta::Entity
+  property :name
+  property :age
+end
+```
 
-### 路由定义
+## 路由定义（`route` 宏）
 
-除了 `get` 之外，我们还支持 `post`、`put`、`patch`、`delete` 四个方法。同时后面可跟一个路径表示路的路径：
+在 `Meta::Application` 类内，第一个能做的事情就是定义路由。`route` 方法（以后我们称这种特定的 DSL 方法为“宏”）定义一个具体的路由（即接口）：
 
 ```ruby
 class DemoApp < Meta::Application
-  post do
-    # ...
+  route '/', :get do
+    # 块内定义路由的详细元素
   end
+end
+```
+
+###  HTTP 路径和方法
 
-  put '/foo' do
+`route` 方法接受一个路径字符串和一个 HTTP 方法，并且可接受一个块用于定义路由的详细元素（将在后面讲到）。HTTP 方法我们一共支持五种，包括 `get`、`post`、`put`、`patch`、`delete`. 为此，我们提供了五个便捷方法用于简化 `route` 方法调用的书写，举例：
+
+```ruby
+class DemoApp < Meta::Application
+  get do # 当路径为 `/` 时，路径参数可以省略
     # ...
   end
 
-  patch '/bar' do
+  post '/foo' do
     # ...
   end
 
+  put '/foo/bar' do
+    # ...
+  end
+  
+  patch '/foo/bar' do
+    # ...
+  end
+  
   delete '/foo/bar' do
     # ...
   end
 end
 ```
 
-以上方法只是 `route(path, method, &block)` 的简写，例如 `put '/foo'` 可以完整地写为 `route '/foo', :put`.
+> 因为这种写法更为清晰并且视觉效果更好，教程的以后都用 `get`、`post`、`put`、`patch`、`delete` 五个方法代替 `route` 方法的调用。除非是只用到路径而不关心 HTTP 方法的情形。
 
-### 路径定义
+### 通配符路径
 
-路径中可以包括参数：
+当定义路由 `route /foo/bar` 时，它匹配的是完整的路径 `/foo/bar`. 当你需要匹配一堆路径时，需要为路由加上通配符符号。`:` 和 `*` 是通配符符号的两种，前者匹配一个部分，后者尽可能多地匹配剩余的部份。这么说如果没说清楚，我举两个例子即可明白：
 
 - `/foo/:id`：它将匹配诸如 `/foo/1`、`/foo/bar` 等路径，但不能匹配 `/foo/a/b/c` 这样的路径。
 - `/foo/*path`：它可以匹配 `/foo`、`/foo/bar`、`/foo/a/b/c` 等格式的路径。
 
-凡是路径中带有命名参数的都能被访问到，例如 `request.params['id']`、`request.params['path']` 。（注意，方括号内一定得是字符串）
+> 通配符符号后面的单词（`id` 和 `path`）是参数名称，它将路由中与其匹配的部分放到参数中可访问。这里先提一下，通过 `request.params['id']`、`request.params['path']` 可以访问到路由当中匹配的部分。
 
-如果你不需要后续访问到参数，可以忽略命名。不过我认为加个名字语义上更加友好，尽管你不必用到。
+如果你不需要后续访问到参数，可以忽略命名：
 
 - `/foo/:`
 - `/foo/*`
 
-在定义参数时要学会不拘一格，试想一下以下的路径定义将匹配哪些：
+再举两个路由参数的示例：
 
-- `/foo/:id/bar`
-- `/foo/*/bar`
+- `/foo/:id/bar`：匹配诸如 `/foo/1/bar`、`/foo/2/bar` 等路径
+- `/foo/*/bar`：匹配 `/foo/bar`、`/foo/a/bar`、`/foo/a/b/bar`、`/foo/a/b/c/bar` 等格式的路径。
 
-### 嵌套路由
+### 定义路由的元信息（`meta` 宏）
 
-用 `route` 方式定义的路由是不支持嵌套的。有一个专门为定义嵌套路由而存在的命令：`namespace`.
+在 `route` 宏内部，可使用两个宏： `meta` 宏定义路由的元信息，`action` 宏定义路由的执行逻辑。
 
-```ruby
-class DemoApp < Meta::Application
-  namespace '/user' do
-    get do
-      title '获取用户详情'
-    end
+首先，通过 `meta` 宏定义路由的“元”信息。注意，“元”信息的作用是双向的，既可以定义接口的文档，也可以约束接口的行为。例如，在 ` meta` 宏内定义参数：
 
-    put do
-      title '更新用户详情'
+```ruby
+post '/users' do
+  meta do
+    params do
+      param :name, type: 'string', description: '姓名'
+      param :age, type: 'integer', description: '年龄'
     end
   end
 end
 ```
 
-### 钩子
+它会产生两个方面的效果：
 
-*（如果不涉及到钩子和异常拦截，嵌套路由将毫无意义。）*
+1. 文档方面：接口文档的参数部分会暴露出两个参数：`name`、`age`，并声明它的类型和描述信息。
+2. 业务逻辑方面：业务代码执行时，通过标准的方法获取参数时会对参数作校验。这里面它只会提取出参数的两个字段（`name` 和 `age`），并对它们俩的类型作校验。如果参数不符合定义，会向客户端抛出一个错误。
 
-正如名字所表达的那样，`before` 就是 before 钩子，`after` 就是 after 钩子。将以上例子加上 `before` 钩子将如下：
+#### `meta` 宏一览
 
-```ruby
-class DemoApp < Meta::Application
-  namespace '/user' do
-    before do
-      @user = get_user
-    end
+`meta` 宏内部现在只提供了以下五个方法：
 
-    get do
-      title '获取用户详情'
+```ruby
+post '/users' do
+  meta do
+    title '创建用户'
+    description '接口的详细描述'
+    tags ['User'] # 定义接口的 Tag，传递一个数组
+    params do
+      # 内部定义参数结构
     end
-
-    put do
-      title '更新用户详情'
+    status 200 do
+      # 内部定义返回值结构
     end
   end
 end
 ```
 
-同时还支持 `around` 钩子（*试验特性*）：
+以上，`title`、`description`、`tags` 宏分别定义接口的标题、描述信息和标签列表。`params` 和 `status` 宏定义接口的参数和返回值，其内部定义比较复杂，将在后面详细讲解。
 
-```ruby
-class DemoApp < Meta::Application
-  before { puts 1 }
-  before { puts 2 }
-  around { |next_action|
-     puts 3
-     next_action.execute(self)
-     puts 5
-  }
-  after { puts 6 }
-  after { puts 7 }
+#### `meta` 宏展开
+
+`meta` 宏可以展开定义，亦即可以直接在 `route` 定义内部直接使用 `meta` 宏定义的语法，它是 `route` 定义内部提供的一种快捷方式：
 
-  get '/request' do
-    puts 4
+```ruby
+post '/users' do
+  title '创建用户'
+  description '接口的详细描述'
+  tags ['User'] # 定义接口的 Tag，传递一个数组
+  params do
+    # 内部定义参数结构
+  end
+  status 200 do
+    # 内部定义返回值结构
   end
 end
 ```
 
-所有钩子的执行顺序是：
+> 由于展开定义的方式写起来更加便捷，因此后面的教程示例都将采取这样的写法。
 
-1. 首先执行 `before` 钩子，按照定义的顺序执行。
-2. 然后执行 `around` 钩子的前半部分，按照定义的顺序执行。
-3. 然后执行路由方法。
-4. 然后执行 `around` 钩子的后半部分，按照定义的顺序执行。
-5. 最后执行 `after` 钩子，按照定义的顺序执行。
+### 定义路由的执行逻辑（`action` 宏）
 
-### 异常拦截
+`action` 宏定义业务代码部分。将上面的 `POST /users` 接口的逻辑实现定义完全，大概率是以下这个样子：
 
-在 `namespace` 中使用 `rescue_error` 拦截异常。
+```ruby
+post '/users' do
+  # ... 定义路由的 meta 部分
+  action do
+    user = User.create!(params[:user])
+    render :user, user
+  end
+end
+```
+
+其中，用到的 `params` 方法和 `render` 方法将在后面讲到。
+
+## 层次化地定义路由（`namespace` 宏）
+
+### 使用 `namespace` 宏定义嵌套路由
 
 ```ruby
 class DemoApp < Meta::Application
-  namespace '/user' do
-    rescue_error RecordNotFound do |e|
-      response.status = 404
-      response.body = ["所访问的资源不存在"]
+  get do # 匹配 GET /
+    # ...
+  end
+
+  namespace '/foo' do
+    get do # 匹配 GET /foo
+      # ...
+    end
+
+    post '/bar' do # 匹配 POST /foo/bar
+      # ...
+    end
+    
+    namespace '/baz' do
+      # ... 匹配前缀为 /foo/baz
     end
   end
 end
 ```
 
-### 关于嵌套的进一步说明
+`namespace` 宏是定义父级结构的，它不能定义到具体的路由，它的内部需要有 `namespace` 宏或 `route` 宏定义更具体的结点。**`namespace` 宏匹配的是路径的前缀。**
+
+而 `route` 宏是最深层次的结构，它定义的是具体的路由和它的行为，它的内部不能有 `namesapce` 宏及 `route` 宏。**`route` 宏要匹配完整的路径。**
+
+> 为什么要定义一个 `namespace` 宏，它不仅仅是减少路径的重复代码这么简单。综合来讲，`namespace` 宏有如下作用：
+>
+> 1. 通过组合 `namespace` 和 `route` 宏来定义应用的层次结构。
+> 2. `namespace` 内可定义钩子，用于公共的运行逻辑。
+> 3. 可定义 `namespace` 级的异常拦截处理方法。
+> 4. 在 `namespace` 定义 `meta` 宏，可定义公共的“元”信息。
+
+### 钩子
+
+`namesapce` 内提供了两种钩子：`before`、`after`. 它在整个 `namespace` 层级执行一遍。
 
-钩子只在当前作用域和它的子作用域下起作用，父级作用域不会起作用。
+正如名字所表达的那样，`before` 在 `action` 宏之前执行，`after` 在 `action` 宏之后执行。
 
 ```ruby
 class DemoApp < Meta::Application
   namespace '/foo' do
     before do
-      @foo = 'foo'
+      puts 1
     end
 
+    after do
+      puts 2
+    end
+    
     get do
       action do
-        p @foo # 'foo'
-        p @bar # nil
+        puts 3
       end
     end
 
-    namespace '/bar' do
-      before do
-          @foo = 'foo'
-      end
-
-      get do
-        action do
-          p @foo # 'foo'
-          p @bar # 'bar'
-        end
+    put do
+      action do
+        puts 4
       end
     end
   end
 end
 ```
 
-异常拦截先拦截子作用域；如果拦截失败则继续在父作用域下拦截。
+当用户访问 `GET /foo` 接口时，依次打印数字 `1`、`3`、`2`；当用户访问 `PUT /foo` 接口时，依次打印数字 `1`、`4`、`2`.
+
+#### `around` 钩子（实验特性）
+
+Meta 框架同时还支持 `around` 钩子， `around` 钩子会包裹 `action` 执行：
 
 ```ruby
 class DemoApp < Meta::Application
   namespace '/foo' do
-    rescue_error ErrorOne do
-      # 它将捕获 '/foo' 路由下的异常
+    around do |next_action|
+      puts 1
+      next_action.execute(self)
+      puts 2
+    end
+    
+    get do
+      action do
+        puts 3
+      end
     end
 
-    namespace '/bar' do
-      rescue_error ErrorTwo do
-        # 它将捕获 '/foo/bar' 路由下的异常
+    put do
+      action do
+        puts 4
       end
     end
   end
 end
 ```
 
-### 模块
+同样的，当用户访问 `GET /foo` 接口时，依次打印数字 `1`、`3`、`2`；当用户访问 `PUT /foo` 接口时，依次打印数字 `1`、`4`、`2`.
+
+> `around` 钩子现在还处于实验阶段，不建议实际开发中使用。当 `around` 钩子混合定义 `before`、`after` 钩子时，其执行的顺序比较混乱。而且，现在的 `around` 钩子还无法覆盖参数解析和返回值渲染的过程，这让它们的应用范围受到限制。当需要完整覆盖接口执行的全周期时，推荐使用 Rack 的中间件。最后，一定要在恰当的时机执行 `next_action.execute(self)`，否则后续的动作将不会得到执行。 `next_action.execute(self)` 调用稍显繁琐，不够优雅。
+
+#### 所有钩子的执行顺序
+
+如果只包含 `before` 和 `after` 钩子，则执行的顺序是：
 
-`Meta::Application` 可以像 `namespace` 一样，定义路由、设置 before/after 钩子、拦截异常等。将以上例子里 `/foo` 的部分抽成一个模块如下：
+1. `before` 钩子先执行，按照定义的顺序；
+2. 接着执行 `action` 定义的块；
+3. 最后执行 `after` 钩子，按照定义的顺序。
+
+举例（以下按照 `1`、`2`、`3` 的数字顺序执行）：
 
 ```ruby
-class Foo < Meta::Application
-  rescue_error ErrorOne do
-    # 它将捕获 '/foo' 路由下的异常
-  end
+class DemoApp < Meta::Application
+  namespace '/foo' do
+    before { puts 1 }
+    before { puts 2 }
+    after { puts 4 }
+    after { puts 5 }
 
-  namespace '/bar' do
-    rescue_error ErrorTwo do
-      # 它将捕获 '/foo/bar' 路由下的异常
+    get '/request' do
+      puts 3
     end
   end
 end
 ```
 
-为达到同样的效果，我们可以在 `DemoApp` 下应用这个模块：
+如果还包含 `around` 钩子，则会复杂一些，但大体上是：
+
+1. 最先执行的是 `before` 钩子以及 `around` 钩子的前半部分，按照定义的顺序；
+2. 接着执行 `action` 定义的块；
+3. 然后执行 `after` 钩子，按照定义的顺序；
+4. 最后执行 `around` 钩子的后半部分，按照定义的**逆序**执行。
+
+举例（以下按照 `1`、`2`、`3` 的数字顺序执行）：
 
 ```ruby
 class DemoApp < Meta::Application
   namespace '/foo' do
-    apply Foo
+    before { puts 1 }
+    around { |next_action|
+       puts 2
+       next_action.execute(self)
+       puts 9
+    }
+    around { |next_action|
+       puts 3
+       next_action.execute(self)
+       puts 8
+    }
+    before { puts 4 }
+    after { puts 6 }
+    after { puts 7 }
+
+    get '/request' do
+      puts 5
+    end
   end
 end
 ```
 
-模块应用最常用的场景是将接口分离到单独的文件中定义。这里我贴出我在一个实际项目中的模块划分：
+#### 使用钩子的注意事项
+
+请注意，钩子的执行顺序是严格按照以上顺序执行的，与你定义的顺序无关。请确保 `before` 和 `around` 钩子优先于 `after` 的顺序定义，因为它们的执行也是优先于 `after` 的。
+
+另外，钩子的执行不会覆盖参数解析和返回值渲染，亦即 `before` 钩子在参数解析之后执行，`after` 钩子在返回值渲染之前执行，而 `around` 钩子亦不会覆盖参数解析和返回值渲染。
+
+钩子不会中断执行。如果要在钩子中中断程序的执行，可使用 `abort_execution!` 方法：
 
 ```ruby
-class OpenAPIApp < Meta::Application
-  apply API::Logins
-  apply API::Users
-  apply API::Organizations
-  apply API::Projects
-  apply API::Versions
-  apply API::Members
+before do
+  token = request.get_header('HTTP_X_TOKEN')
+  // ... parse token
+rescue TokenInvalidError => e
+  response.status = 401
+  response.message = "Token 格式异常：#{e.message}"
+  abort_execution!
 end
 ```
 
-## 路由内部定义
+`abort_execution!` 同时会跳过返回值渲染的执行。
 
-现在我们关注路由内部细节的定义，包括标题、描述、参数、返回值乃至于如何实现业务逻辑等。我们知道，路由是通过 `route` 方法（以及它的一系列便捷方法 `get`、`post` 等），也就是说我们现在开始关注 `route` 方法内部能定义什么。
+冷知识：`Meta::Application` 本身也可视为一个命名空间定义，`namespace` 内能用到的方法也可以在 `Meta::Application` 内使用。
 
-本来想大书特书，结果发现以下代码示例便能将用到的宏命令列举完毕。
+### 异常拦截
+
+在 `namespace` 中可使用 `rescue_error` 拦截异常。
 
 ```ruby
-route '/user', :put do
-  title '更新用户'
-  description '接口的详细描述'
-  tags ['User'] # 传递一个数组
-  params do
-    # 定义参数
-    param :user do
-      param :name
-      param :age
+class DemoApp < Meta::Application
+  namespace '/users/:id' do
+    rescue_error ActiveRecord::RecordNotFound do |e|
+      response.status = 404
+      response.body = ["所访问的资源不存在"]
     end
-  end
-  status 200 do
-    # 定义返回值，其中 200 是状态码
-    expose :user do
-      expose :name
-      expose :age
+    
+    get do
+      action do
+        user = User.find(params[:id])
+      end
     end
   end
-  action do
-    # 业务逻辑在这里实现，通过 params 方法访问参数，render 方法渲染实体
-    user = get_user
-    user.update!(params[:user])
-    render :user, user
-  end
 end
 ```
 
-### `meta` 命令
+以下是 Meta 框架抛出的异常：
+
+- `Meta::Errors::NoMatchingRoute`：路由不匹配时。
+- `Meta::Errors::ParameterInvalid`：参数存在异常时。
+- `Meta::Errors::RenderingInvalid`：响应值存在异常时。
+- `Meta::Errors::UnsupportedContentType`：框架只支持 `application/json` 的参数格式。当客户端的请求体不是这个格式时，会抛出这个错误。
 
-除 `action` 之外，`route` 块下其余的命令都与文档的生成相关。它们都可以被汇总到一个称为 `meta` 的块内：
+#### 嵌套命名空间下的异常拦截
+
+拦截异常先在子作用域下拦截；如果拦截失败则继续在父作用域下拦截。下面的例子中：
 
 ```ruby
-route '/user', :put do
-  meta do
-    title '更新用户'
-    description '接口的详细描述'
-    tags ['User'] # 传递一个数组
-    params do
-      # 定义参数
+class DemoApp < Meta::Application
+  namespace '/foo' do
+    rescue_error ErrorOne do
+      puts "rescued in /foo" #（1）
     end
-    status 200 do
-      # 定义返回值
+
+    rescue_error ErrorTwo do
+      puts "rescued in /foo" #（2）
+    end
+
+    namespace '/bar' do
+      rescue_error ErrorOne do
+        puts "rescued in /foo/bar" #（3）
+      end
+      
+      get do
+        action do
+        	raise ErrorOne
+      	end
+      end
+      
+      put do
+        action do
+        	raise ErrorTwo
+      	end
+      end
     end
   end
-  action do
-    # 业务逻辑仍在这里实现
+end
+```
+
+调用 `GET /foo/bar` 请求时会在（3）处被捕获；调用 `PUT /foo/bar` 请求时会在（2）处被捕获。
+
+#### `Meta::Errors::NoMatchingRoute` 只能在顶层被捕获
+
+由于框架实现的特殊性，异常 `Meta::Errors::NoMatchingRoute` 只会在顶层抛出。因此，只有在 `namespace` 的顶层捕获才有效果。
+
+```ruby
+class DemoApp < Meta::Application
+  # 在此捕获有效
+  rescue_error Meta::Errors::NoMatchingRoute do |e|
+    response.status = 404
+    response.body = ["404 Not Found"]
+  end
+
+  namespace '/foo' do
+    # 在此捕获无效
+    rescue_error Meta::Errors::NoMatchingRoute do |e|
+      response.status = 404
+      response.body = ["404 Not Found"]
+    end
   end
 end
 ```
 
-### `namespace` 下的 `meta` 命令
+即使是上面的例子，调用 `GET /foo/bar` 请求时也只有顶层的异常拦截起了作用。
 
-`namespace` 下可以也定义 `meta` 块，它可以定义接口声明的公共部分，应用到它的子路由下：
+### `namespace` 的 `meta` 宏
+
+同 `route` 宏内，`namespace` 宏内部可以定义 `meta` 宏。`namespace` 定义的 `meta` 宏定义下属路由的公共部分，其会应用到全部子路由，除非在 `route` 宏内复写。
 
 ```ruby
-namespace '/user/:id' do
+namespace '/users/:id' do
+  # 以下 meta 内定义的部分会应用到 GET /users/:id 和 PUT /users/:id 两个路由。
+  # 其中，因为 title 两个路由有重写，因此会使用两个路由自己的 title 定义。
+  # description 两个路由都没有独自定义，因此会统一使用 meta 中的定义。
+  # tags 同理，它们都挂载在同一个 Tag 下。
+  # params 定义比较特殊，子路由下的定义不是复写而是补充。因此 GET /users/:id 包含一个参数 id，PUT /users/:id 包含了两个参数
+  # id 和 user.
+  # status 与 params 同理，但由于子路由内没有 status 定义，从而它们两个都是使用 meta 中的定义，即返回一个 user 属性。
   meta do
-    # 在 namespace 下定义 title 和 description 没有意义
+    title '处理用户详情'
+    description '通过路径参数获取用户数据，并对用户数据做一定的处理，比如查看、更新'
     tags ['User'] # 该 namespace 下的接口归到 User 标签下
     params do # 定义共同参数
       param :id
@@ -375,6 +517,206 @@ namespace '/user/:id' do
 end
 ```
 
+## 路由的执行环境 （`Meta::Execution`）
+
+当路由在执行过程中，会将块绑定到一个 `Meta::Execution` 实例中执行。`before`、`after` 等钩子，`action` 定义的块内，以及异常拦截的过程中，其执行环境都会绑定到当前的  `Meta::Execution` 实例。
+
+```ruby
+class DemoApp < Meta::Application
+  before do
+    @current_user = "Jim" # 设置一个环境变量
+  end
+  
+  rescue_error StandardError do
+    p @current_user # 可以访问先前设置的实例变量
+  end
+  
+  get '/user' do
+    action do
+      p @current_user # 可以访问先前设置的实例变量
+      raise # 抛出异常
+    end
+  end
+end
+```
+
+### `Meta::Execution` 提供的方法。
+
+#### `#request`
+
+`request` 方法返回 [`Rack::Request`](https://www.rubydoc.info/gems/rack/Rack/Request) 实例，它是 Rack 框架提供的包装类，用于简化 HTTP 操作。
+
+#### `#response`
+
+`response` 方法返回 [`Rack::Response`](https://www.rubydoc.info/gems/rack/Rack/Response) 的实例，它是 Rack 框架的包装类，用于简化 HTTP 操作。
+
+#### `#params`
+
+不要与 `.params` 宏所混淆，它是 `Meta::Execution` 提供的实例方法，返回解析后的参数。参数的解析参考 `params` 宏的定义。
+
+#### `#render`
+
+定义实际响应体时使用 `render` 方法。`render` 方法参考 `status` 定义的响应体格式过滤和验证字段。
+
+#### `#abort_execution!`
+
+中断后续的执行。如果是在 `before` 块中执行这个方法，则跳过后续的 `before`、`action` 和 `after` 块；如果是在 `action` 块中执行这个方法，则跳过 `after` 块。注意，这个方法会跳过响应体渲染阶段。
+
+### 共享模块
+
+不要在 `Meta::Application` 内部定义方法，在它内部直接定义的方法应用到 `Meta::Execution` 实例。如果需要在当前以及后续路由用到公共的方法，可以在 `shared` 块内定义：
+
+```ruby
+class DemoApp < Meta::Application
+  shared do
+    def current_user
+      @current_user
+    end
+  end
+  
+  before do
+    @current_user = "Jim" # 设置一个环境变量
+  end
+  
+  get '/user' do
+    action do
+      p current_user # 在路由内访问方法
+    end
+  end
+  
+  namespace '/foo' do
+    get '/user' do
+      action do
+        p current_user # 在子命名空间内也能访问到方法
+      end
+    end
+  end
+end
+```
+
+除此之外，`shared` 的参数也接受模块。
+
+```ruby
+module HelperFoo
+  def foo; 'foo' end
+end
+
+module HelperBar
+  def bar; 'bar' end
+end
+
+class DemoApp < Meta::Application
+  shared HelperFoo, HelperBar
+  
+  get '/user' do
+    action do
+      p foo
+      p bar # 可访问模块定义的方法
+    end
+  end
+end
+```
+
+## 模块（`Meta::Application`）
+
+### `Meta::Application` 等同于 `namespace` 定义
+
+要知道 `Meta::Application`，第一个事情就是它等同于 `namespace` 定义。像 `namespace` 一样，能定义路由、钩子、异常拦截的地方都可以在 `Meta::Application` 内直接定义。
+
+```ruby
+class DemoApp < Meta::Application
+  # meta 定义，能应用到下属子路由的所有地方
+  meta do
+    # ...
+  end
+  
+  # 它将捕获下属子路由的所有异常
+  rescue_error Exception do
+    # ...
+  end
+  
+  # 钩子，最先执行
+  before do
+    # ...
+  end
+  
+  # 钩子，最后执行
+  after do
+    # ...
+  end
+
+  # 定义嵌套命名空间
+  namespace '/...' do
+    # ...
+  end
+  
+  # 也可以直接定义路由
+  route '/...', :post do
+    # ...
+  end
+end
+```
+
+你可以将 `Meta::Application ` 视为路径定义为 `/` 的命名空间。
+
+### `Meta::Application` 是可复用的模块
+
+遇到大型项目时，将 API 定义分离成若干个单独的文件更好的组织。做到这一点，就用到 `namespace` 中提供的 `apply` 方法。
+
+继承自 `Meta::Application` 的类都是一个模块，它可以在 `namespace` 中被复用。
+
+```ruby
+class Foo < Meta::Application
+  route '/foo' do
+    # ...
+  end
+end
+
+class DemoApp < Meta::Application
+  apply Foo
+end
+```
+
+将定义写在一个类里，其等价于：
+
+```ruby
+class DemoApp < Meta::Application
+  route '/foo' do
+    # ...
+  end
+end
+```
+
+`apply` 方法还可跟一个参数 `tags: [...]`，统一覆盖被引入的模块在渲染文档时声明的 `tags`：
+
+```ruby
+class OpenAPIApp < Meta::Application
+  apply API::Logins, tags: ['Login']
+  apply API::Users, tags: ['User']
+  apply API::Organizations, tags: ['Organization']
+  apply API::Projects, tags: ['Project']
+  apply API::Versions, tags: ['Version']
+  apply API::Members, tags: ['Member']
+end
+```
+
+### `Meta::Application` 是一个 Rack 应用
+
+`Meta::Application` 同时也是一个 Rack 应用，将它挂载在 Rack 下可以直接作为一个服务运行。我们看一个最简单的 `Meta::Application` 实例：
+
+```ruby
+class DemoApp < Meta::Application
+  route '/', :get do
+    title '应用的根路径'
+    action do
+      response.body = ["Hello, world!"]
+    end
+  end
+end
+```
+
+> 将它挂载在 Rack 下并访问 `http://localhost:9292` 你将看到接口返回 `"Hello, world"` 文本。
+
 ## 参数定义
 
 本节介绍参数和返回值如何定义。因为 Meta 框架在底层不区分参数和返回值，它们都统一为“实体”的概念。因此，当涉及到语法细节时，在参数、返回值、实体内都是一致的。