meta-api 0.0.7 → 0.0.9

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

@@ -1,1647 +0,0 @@
-# 教程
-
-现有的 Web API 框架并不关注文档的问题，文档往往是作为插件挂载到框架上的。但是，文档和业务实现并不需要割裂开，它们在很大程度上应该是耦合在一起的。比方说，某个接口我定义了参数如此，就该自动生成一致的文档向前端告知；同样，当我提供了文档是如此后，我的接口实现就该自动地约束为这样实现。
-
-Meta 框架天生就是将文档和实现统一起来的，并始终致力于此（如果真的有什么不一致或者不到位的地方，那只能说框架实现上尚有欠缺，并不能从思想上说本该如此）。Meta 框架与 Swagger 合作，致力于产生符合 Restful 和社区规范的文档格式。它提供了几乎完整的描述接口信息的宏命令，并且在描述接口的同时就能基本实现接口的一些约束，其中最重要的莫过于对参数和返回值的声明。
-
-## 准备工作
-
-在正式阅读本教程之前，有一些*准备工作*需要提前了解的。
-
-### 只接受 JSON
-
-**只接受格式为 `application/json` 的请求体参数，并且响应实体的格式一律为 `application/json`.**
-
-这在当前的环境下并不算太大的限制，如果你是致力于新项目的开发的话。但是，如果你处理旧项目，并且要求格式为 `application/json` 之外的格式，如 `application/xml`，则框架目前是不能自动处理的。
-
-这种限制只存在于通过 `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 钩子、异常拦截等概念。
-
-从命名空间引申出的模块的概念也很重要。模块本身也是一个命名空间，命名空间用到的功能都可以用在模块中。除此之外，模块还用来组织大型应用的结构。最后，模块本身也是一个 Rack 应用，可以直接放在服务器下运行。
-
-接下来是重点，我们将深入参数和返回值的定义。虽然说前面已经提到参数和返回值的知识，但仅覆盖最简单同时也是最常用的场景。参数和返回值的知识实在是太大了，有必要专门划出一个章节来介绍它。这里提一下，参数和返回值在 Meta 框架里都统一为一个叫做实体的概念，因此你只需要学会定义一种就能够同时定义两者了。
-
-最后，将是一个生成文档的方法。虽然它很简单，仅仅是一个方法，但它如此重要以至于我不得不专门划出一个章节来强调它的重要性。
-
-文章的最后是特殊用法举例。说实话，我还没想好把它放哪，但它确实列举了几个比较常见的场景。
-
-### 继承和宏定义
-
-在使用 Meta 框架提供的组件时，我们往往先要继承一个类，然后直接在类定义中使用宏命令。所谓的宏命令其实就是一个 Ruby 方法，只不过在 DSL 术语中我们将它称为“宏”。
-
-例如，定义一个 API，我们继承的是 `Meta::Application` 类，然后在类中使用 `route` 宏定义路由：
-
-```ruby
-class DemoApp < Meta::Application
-  route '/foo', :get do
-    # ... 具体的宏定义
-  end
-end
-```
-
-再比如继承 `Meta::Entity` 定义一个实体，实体内使用 `property` 宏定义属性：
-
-```ruby
-class UserEntity < Meta::Entity
-  property :name
-  property :age
-end
-```
-
-## 路由定义（`route` 宏）
-
-在 `Meta::Application` 类内，第一个能做的事情就是定义路由。`route` 方法（以后我们称这种特定的 DSL 方法为“宏”）定义一个具体的路由（即接口）：
-
-```ruby
-class DemoApp < Meta::Application
-  route '/', :get do
-    # 块内定义路由的详细元素
-  end
-end
-```
-
-###  HTTP 路径和方法
-
-`route` 方法接受一个路径字符串和一个 HTTP 方法，并且可接受一个块用于定义路由的详细元素（将在后面讲到）。HTTP 方法我们一共支持五种，包括 `get`、`post`、`put`、`patch`、`delete`. 为此，我们提供了五个便捷方法用于简化 `route` 方法调用的书写，举例：
-
-```ruby
-class DemoApp < Meta::Application
-  get do # 当路径为 `/` 时，路径参数可以省略
-    # ...
-  end
-
-  post '/foo' do
-    # ...
-  end
-
-  put '/foo/bar' do
-    # ...
-  end
-  
-  patch '/foo/bar' do
-    # ...
-  end
-  
-  delete '/foo/bar' do
-    # ...
-  end
-end
-```
-
-> 因为这种写法更为清晰并且视觉效果更好，教程的以后都用 `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` 等格式的路径。
-
-> 通配符符号后面的单词（`id` 和 `path`）是参数名称，它将路由中与其匹配的部分放到参数中可访问。这里先提一下，通过 `request.params['id']`、`request.params['path']` 可以访问到路由当中匹配的部分。
-
-如果你不需要后续访问到参数，可以忽略命名：
-
-- `/foo/:`
-- `/foo/*`
-
-再举两个路由参数的示例：
-
-- `/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` 宏内部，可使用两个宏： `meta` 宏定义路由的元信息，`action` 宏定义路由的执行逻辑。
-
-首先，通过 `meta` 宏定义路由的“元”信息。注意，“元”信息的作用是双向的，既可以定义接口的文档，也可以约束接口的行为。例如，在 ` meta` 宏内定义参数：
-
-```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`），并对它们俩的类型作校验。如果参数不符合定义，会向客户端抛出一个错误。
-
-#### `meta` 宏一览
-
-`meta` 宏内部现在只提供了以下五个方法：
-
-```ruby
-post '/users' do
-  meta do
-    title '创建用户'
-    description '接口的详细描述'
-    tags ['User'] # 定义接口的 Tag，传递一个数组
-    params do
-      # 内部定义参数结构
-    end
-    status 200 do
-      # 内部定义返回值结构
-    end
-  end
-end
-```
-
-以上，`title`、`description`、`tags` 宏分别定义接口的标题、描述信息和标签列表。`params` 和 `status` 宏定义接口的参数和返回值，其内部定义比较复杂，将在后面详细讲解。
-
-#### `meta` 宏展开
-
-`meta` 宏可以展开定义，亦即可以直接在 `route` 定义内部直接使用 `meta` 宏定义的语法，它是 `route` 定义内部提供的一种快捷方式：
-
-```ruby
-post '/users' do
-  title '创建用户'
-  description '接口的详细描述'
-  tags ['User'] # 定义接口的 Tag，传递一个数组
-  params do
-    # 内部定义参数结构
-  end
-  status 200 do
-    # 内部定义返回值结构
-  end
-end
-```
-
-> 由于展开定义的方式写起来更加便捷，因此后面的教程示例都将采取这样的写法。
-
-### 定义路由的执行逻辑（`action` 宏）
-
-`action` 宏定义业务代码部分。将上面的 `POST /users` 接口的逻辑实现定义完全，大概率是以下这个样子：
-
-```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
-  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
-      puts 1
-    end
-
-    after do
-      puts 2
-    end
-    
-    get do
-      action do
-        puts 3
-      end
-    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
-    around do |next_action|
-      puts 1
-      next_action.execute(self)
-      puts 2
-    end
-    
-    get do
-      action do
-        puts 3
-      end
-    end
-
-    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` 钩子，则执行的顺序是：
-
-1. `before` 钩子先执行，按照定义的顺序；
-2. 接着执行 `action` 定义的块；
-3. 最后执行 `after` 钩子，按照定义的顺序。
-
-举例（以下按照 `1`、`2`、`3` 的数字顺序执行）：
-
-```ruby
-class DemoApp < Meta::Application
-  namespace '/foo' do
-    before { puts 1 }
-    before { puts 2 }
-    after { puts 4 }
-    after { puts 5 }
-
-    get '/request' do
-      puts 3
-    end
-  end
-end
-```
-
-如果还包含 `around` 钩子，则会复杂一些，但大体上是：
-
-1. 最先执行的是 `before` 钩子以及 `around` 钩子的前半部分，按照定义的顺序；
-2. 接着执行 `action` 定义的块；
-3. 然后执行 `after` 钩子，按照定义的顺序；
-4. 最后执行 `around` 钩子的后半部分，按照定义的**逆序**执行。
-
-举例（以下按照 `1`、`2`、`3` 的数字顺序执行）：
-
-```ruby
-class DemoApp < Meta::Application
-  namespace '/foo' do
-    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
-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!` 同时会跳过返回值渲染的执行。
-
-冷知识：`Meta::Application` 本身也可视为一个命名空间定义，`namespace` 内能用到的方法也可以在 `Meta::Application` 内使用。
-
-### 异常拦截
-
-在 `namespace` 中可使用 `rescue_error` 拦截异常。
-
-```ruby
-class DemoApp < Meta::Application
-  namespace '/users/:id' do
-    rescue_error ActiveRecord::RecordNotFound do |e|
-      response.status = 404
-      response.body = ["所访问的资源不存在"]
-    end
-    
-    get do
-      action do
-        user = User.find(params[:id])
-      end
-    end
-  end
-end
-```
-
-以下是 Meta 框架抛出的异常：
-
-- `Meta::Errors::NoMatchingRoute`：路由不匹配时。
-- `Meta::Errors::ParameterInvalid`：参数存在异常时。
-- `Meta::Errors::RenderingInvalid`：响应值存在异常时。
-- `Meta::Errors::UnsupportedContentType`：框架只支持 `application/json` 的参数格式。当客户端的请求体不是这个格式时，会抛出这个错误。
-
-#### 嵌套命名空间下的异常拦截
-
-拦截异常先在子作用域下拦截；如果拦截失败则继续在父作用域下拦截。下面的例子中：
-
-```ruby
-class DemoApp < Meta::Application
-  namespace '/foo' do
-    rescue_error ErrorOne do
-      puts "rescued in /foo" #（1）
-    end
-
-    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
-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
-```
-
-即使是上面的例子，调用 `GET /foo/bar` 请求时也只有顶层的异常拦截起了作用。
-
-### `namespace` 的 `meta` 宏
-
-同 `route` 宏内，`namespace` 宏内部可以定义 `meta` 宏。`namespace` 定义的 `meta` 宏定义下属路由的公共部分，其会应用到全部子路由，除非在 `route` 宏内复写。
-
-```ruby
-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
-    title '处理用户详情'
-    description '通过路径参数获取用户数据，并对用户数据做一定的处理，比如查看、更新'
-    tags ['User'] # 该 namespace 下的接口归到 User 标签下
-    params do # 定义共同参数
-      param :id
-    end
-    status 200 do # 定义共同返回值
-      expose :user, type: 'object'
-    end
-  end
-
-  get do
-    title '返回用户详情'
-    action do
-      user = User.find(params[:id]) # params 包括 id 字段
-      render :user, user # render 包括 user 字段
-    end
-  end
-
-  put do
-    title '更新用户'
-    params do
-      # 补充参数 user
-      param :user, type: 'object'
-    end
-    action do
-      user = User.find(params[:id])
-      user.update!(params[:user]) # params 包括 id、user 字段
-      render :user, user # render 包括 user 字段
-    end
-  end
-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 框架在底层不区分参数和返回值，它们都统一为“实体”的概念。因此，当涉及到语法细节时，在参数、返回值、实体内都是一致的。
-
-可以说，有关实体的定义，是 Meta 框架中细节最多的地方。在撰写这一章节的时候，我尝试写过很多遍，都无法很好地将方方面面说明清楚。我在行文时，一方面希望大家在入门的时候方便，能够很快地定义常用的用法；另一方面，也希望将所涉及的细节都能够阐述清楚，希望大家能够全面了解到 Meta 框架实体定义的方方面。现在，我只能尽可能地做到这两点，却不再强求。我将以场景的形式阐述用法，而不是孤立地介绍每个知识点。
-
-### 初探：参数定义和过滤
-
-在路由中，我们用 `params` 命令定义参数：
-
-```ruby
-post '/users' do
-  params do
-    param :name
-    param :age
-  end
-end
-```
-
-然后，我们可以在 `action` 命令中使用 `params` 方法访问参数。如果我们发送了一个这样的请求：
-
-```bash
-POST '/users' -d '{"name": "Jim", "age": 18}'
-```
-
-我们将在 `action` 命令中获取到这样的参数结构：
-
-```ruby
-post '/users' do
-  action do
-    p params # => { name: "Jim", age: 18 }
-  end
-end
-```
-
-参数解析时有自动过滤的作用，如果我们发送了一个这样的请求：
-
-```bash
-POST '/users' -d '{"name": "Jim", "foo": "foo"}'
-```
-
-我们将在 `action` 命令中获取到这样的参数结构：
-
-```ruby
-post '/users' do
-  action do
-    p params # => { name: "Jim", age: nil }
-  end
-end
-```
-
-可以看到，它的做法是过滤了未定义的 `foo` 字段，并且将没有提供的 `age` 字段设为 `nil`.
-
-### 嵌套：参数的层次结构
-
-一般我在实际项目中不会这么定义，而是更习惯将它们套在一个根字段下，这样做有利于结构的划分和后期的扩展。
-
-```ruby
-post '/users' do
-  params do
-    param :user do
-      param :name
-      param :age
-    end
-  end
-end
-```
-
-以上定义需要接收以下格式的参数：
-
-```bash
-POST '/users' -d '{
-  "user": {
-      "name": "Jim",
-      "age": 18
-  }
-}'
-```
-
-在 `action` 命令中获取到的也是这样的嵌套结构：
-
-```ruby
-post '/users' do
-  action do
-    p params # => { user: { name: "Jim", age: 18 } }
-  end
-end
-```
-
-参数过滤也会发挥作用。如果请求参数传递的是这样的格式：
-
-```ruby
-# HTTP params
-{ "user": { "name": "Jim", "foo": "foo" } }
-```
-
-程序中获取的参数格式将是这样：
-
-```ruby
-# p params
-{ user: { name: "Jim", age: nil } }
-```
-
-如果顶层的 `user` 字段未提供，则整个 `user` 字段将设为 `nil`.
-
-> **提醒：**后续我们会在代码第一行添加 `# HTTP params` 注释表明这是 HTTP 请求的参数格式，`# p params` 注释表明这是程序中获取到的参数格式。
-
-### 类型：参数的约束之一
-
-参数提供很多约束选项，类型只是其中之一。
-
-#### 基本类型定义
-
-将以上的参数定义添加上类型定义，应当是：
-
-```ruby
-params do
-  param :name, type: 'string'
-  param :age, type: 'integer'
-end
-```
-
-类型定义首要的作用是报错，例如以下的参数格式会向客户端抛出 `400 Bad Request`：
-
-```ruby
-# HTTP params
-{ "name": "Jim", "age": "eighteen" }
-```
-
-参数在进行类型校验时是宽容的。如果值能够成功转化为定义的类型，则参数校验不会报错。以下参数不会报错：
-
-```ruby
-# HTTP params
-{ "name": "Jim", "age": "18" }
-```
-
-只不过参数过滤会规范化最终参数的格式，因此以上参数在程序中会获取为：
-
-```ruby
-# p params
-{ name: "Jim", age: 18 }
-```
-
-`age` 字段获取到的是数字类型而非字符串类型。
-
-#### 嵌套类型定义
-
-对于嵌套参数，你可以定义为 `object` 类型。但这是没必要的，因为嵌套参数必然应当是 `object` 类型。以下两个参数定义等价：
-
-```ruby
-params do
-  param :user, type: 'object' do
-    param :name
-    param :age
-  end
-end
-
-params do
-  param :user do
-    param :name
-    param :age
-  end
-end
-```
-
-当定义 `object` 类型时，也可以不提供内部结构，此时将不再进行内部结构的过滤：
-
-```ruby
-params do
-  param :user, type: 'object'
-end
-
-# 接受的 HTTP 请求参数
-{ "user": { "name": "Jim", "age": 18 }}
-{ "user": { "foo": "foo" } }
-{ "user": {} }
-{ "user": nil }
-
-# 不接受的 HTTP 请求参数
-{ "user": "foo" }
-{ "user": 18 }
-{ "user": [] }
-```
-
-记住，不校验和 `object` 类型不是一回事。不提供任何类型时，此时参数接受一切值：
-
-```ruby
-params do
-  param :user
-end
-
-# 以下格式都接受
-{ "user": { "name": "Jim", "age": 18 }}
-{ "user": { "foo": "foo" } }
-{ "user": {} }
-{ "user": nil }
-{ "user": "foo" }
-{ "user": 18 }
-{ "user": [] }
-```
-
-#### 数组类型定义
-
-你可以定义为数组类型，此时参数必须接受为对象数组的格式。
-
-```ruby
-params do
-  param :users, type: 'array' do
-    param :name
-    param :age
-  end
-end
-
-# 接受的参数格式
-# HTTP params
-{
-  "users": [
-    { "name": "Jim", age: 18 },
-    { "name": "Jack", age: 19}
-  ]
-}
-```
-
-有时候我们遇到数组内部不是对象的情况，这时候就不能使用嵌套定义：
-
-```ruby
-params do
-  param :tags, type: 'array'
-end
-```
-
-这个时候参数必须接收数组格式，但内部元素不会做校验。如果希望内部元素也要校验，用 `items` 选项定义内部结构：
-
-```ruby
-params do
-  param :tags, type: 'array', items: { type: 'string' }
-end
-```
-
-#### 完整的类型列表
-
-你能用到的 `type` 取值只能是以下之一：
-
-- `"boolean"`
-- `"integer"`
-- `"number"`
-- `"string"`
-- `"object"`
-- `"array"`
-
-### `required`：参数的约束之二
-
-正如其名，`required` 作“必须”校验。先前说过，未传递的字段会被赋予 `nil` . 然而，若字段被配置为 `required`，则参数校验会报错。以下参数定义中，`age` 字段被配置为 `required`：
-
-```ruby
-# 参数定义
-params do
-  param :name
-  param :age, required: true
-end
-```
-
-以下请求皆会报错：
-
-```ruby
-# HTTP params
-POST '/users' -d '{"name": "Jim"}'
-
-# HTTP params
-POST '/users' -d '{"name": "Jim", age: null}'
-```
-
-> **小提示：**先前说过，将参数套在一个根字段下是一个好的设计习惯。同时，将这个根字段配置为 `required` 也是一个好习惯。
-> 
-> ```ruby
-> # 参数定义
-> params do
->   param :user, required: true do
->     param :name
->     param :age
->   end
-> end
-> ```
-> 
-> 这会杜绝传递诸如 `{}`、`{ "user": null }` 这样的 JSON 格式。
-
-### 其他参数约束
-
-框架自带若干参数验证配置，在本节列举。
-
-#### `required`
-
-`required` 可同时配置 `allow_empty: true` 或 `allow_empty: false` 用以是否接受空字符串或空数组：
-
-```ruby
-params do
-  param :title, require: { allow_empty: false } # 不接受空字符串
-  param :tags, require: { allow_empty: true }   # 可接受空数组
-end
-```
-
-#### `format`
-
-为字符串参数配置 `format` 可限制参数的格式。以下是用到的 `format` 示例：
-
-```ruby
-# 参数定义
-params do
-  param :date, format: /^\d{4}-\d{2}-\d{2}$/
-  param :mobile, format: /^1[3456789]\d{9}$/
-  param :email, format: /^$/
-end
-```
-
-#### `allowable`
-
-通过一个数组配置一个字段可接受的值：
-
-```ruby
-# 参数定义
-params do
-  param :p_state, description: '进程状态', allowable: ["idle", "pending", "running", "exited"]
-  param :gender, description: '性别', allowable: ["male", "female"]
-endparams do
-  param :state, description: '进程状态', allowable: ["idle", "pending", "running", "exited"]
-  param :sex, description: '性别', allowable: ["male", "female"]
-end
-```
-
-> **小提示：**一直忘记说了，我们可以通过 `description` 选项配置字段的描述，这个描述会在生成文档时生效。
-
-#### `validate`：自定义校验
-
-如果以上的校验均不够用，Meta 支持自定义编写校验。`validate` 接受一个块，当校验失败时需要主动地抛出 `Meta::JsonSchema::ValidationError`：
-
-```ruby
-params do
-  raise Meta::JsonSchema::ValidationError, '手机号格式不正确' unless value =~ /^1[3456789]\d{9}$/
-end
-```
-
-### 设置参数的默认值
-
-`default` 选项可设置参数的默认值，当参数未提供或为 `nil` 时，默认值就会起作用：
-
-```ruby
-params do
-  param :age, default: 18 # 通过值设定
-  param :name, default: -> { 'Jim' } # 通过块设定
-end
-```
-
-### 参数在文档中的位置
-
-默认情况下参数是放在 Request Body 下的（作为 `application/json` 的格式的一部分），但参数还可能存在于 path 或 query hash 中。使用 `in` 选项可以定义之，它对框架的执行没有影响，只对文档的生成产生效果。
-
-```ruby
-post '/:in_path' do
-  params do
-    param :in_path, in: 'path'
-    param :in_query, in: 'query'
-    param :in_body, in: 'body'
-  end
-end
-```
-
-## 返回值定义
-
-`status` 宏命令用来定义返回值。你需要传递一个（或多个）状态码，并用一个同样结构的块作为实体的定义。
-
-```ruby
-# 定义简单的返回实体
-status 200 do
-  expose :name, type: 'string'
-  expose :age, type: 'integer'
-end
-
-# 同样支持嵌套 
-status 200 do
-  expose :user do
-      expose :name, type: 'string'
-      expose :age, type: 'integer'
-  end
-end
-
-# 同样支持校验，虽然我觉得校验返回值有点多此一举
-status 200 do
-  expose :user, required: true do
-      expose :name, type: 'string'
-      expose :age, type: 'integer', required: true
-  end
-end
-```
-
-## 实体定义
-
-### 统一参数和返回值
-
-参数和返回值的定义并不需要割裂开，它们在很多行为上是统一的。现在，我们分别单独定义了参数和返回值：
-
-```ruby
-params do
-  param :user do
-    param :name, type: 'string'
-    param :age, type: 'integer'
-  end
-end
-
-status 200 do
-  expose :user do
-    expose :name, type: 'string'
-    expose :age, type: 'integer'
-  end
-end
-```
-
-为将上述定义改造，内部的块可以封装在一个实体内定义：
-
-```ruby
-class UserEntity < Meta::Entity
-  property :name, type: 'string'
-  property :age, type: 'integer'
-end
-```
-
-然后在 `params` 和 `status` 内部使用 `ref` 引用这个实体：
-
-```ruby
-params do
-  param :user, ref: UserEntity
-end
-
-status 200 do
-  expose :user, ref: UserEntity
-end
-```
-
-我们通过继承 `Meta::Entity` 类定义了实体并到处引用，从而简化了代码。这在实践中是推荐的方案。鉴于参数、返回值、实体的定义语法是完全一致的，故而接下来我们将重点进入实体的讲解环节。希望读者清楚的是，以上参数介绍的语法在实体定义中是完全可用的；并且，接下来有关实体的语法也能完全运用到单独的参数和返回值定义块中。
-
-> **小提示：**我们在 `params` 中用 `param` 命令定义参数字段，在 `status` 中用 `expose` 命令定义返回值字段，而在实体定义中这个命令变成了 `property`. 这里需要阐明的是，用 `param`、`expose` 还是 `property` 只是习惯的不同而已，它们的行为都是一致的并且能够混用。例如，你完全可以在 `params` 和 `status` 中一律使用 `property` 命令：
-> 
-> ```ruby
-> params do
->     property :user, ref: UserEntity
-> end
-> 
-> status 200 do
->     property :user, ref: UserEntity
-> end
-> ```
-
-### 实体定义的其他介绍
-
-`param` 和 `expose` 的只会作用到同层的字段，不会作用到实体内部。
-
-数组内部也可以引用实体，只要在字段上加上 `type: "array"` 即可：
-
-```ruby
-params do
-  param :users, type: "array", ref: UserEntity
-end
-```
-
-接下来会涉及之前没提过的配置选项，包括 `param`、`render`、`scope`、`value`、`convert` 等。单独说明某个选项的用法显得枯燥，我接下来将以列举场景的方式说明。
-
-### 如何设置某个字段只作为参数或返回值
-
-由于实体内部既包括参数的字段，也包括返回值的字段，必然有某些字段只可作为参数或返回值。这种情况该如何做呢？我们可以配置 `param: false` 定义这个字段不可作为参数，另外配置 `render: false` 定义这个字段不可用作返回值。如下是一个例子：
-
-```ruby
-class UserEntity < Meta::Entity
-  property :id, param: false # id 字段不可用作参数
-  property :name # name 和 age 字段既可用作参数，也可用作返回值
-  property :age
-  property :password, render: false # password 字段不可用作返回值
-end
-```
-
-虽然有点啰嗦，上述例子如果接收的参数是：
-
-```ruby
-# HTTP params
-{ "id": 1, "name": "Jim", "age": 18, "password": "123456" }
-```
-
-则程序中获取到的参数内容是：
-
-```ruby
-# p params
-{ name: "Jim", age: 18, password: "123456" }
-```
-
-另外，如果我们渲染了如下的数据：
-
-```ruby
-action do
-  render("id" => 1, "name" => "Jim", "age" => 18, "password" => "123456")
-end
-```
-
-则客户端实际得到的 JSON 格式是：
-
-```ruby
-# HTTP Response
-{ "id": 1, "name": "Jim", "age": 18 }
-```
-
-#### 引申：`param` 和 `render` 本质探究
-
-`param` 和 `render` 支持两种格式：其一是刚刚见过的 `false`，它将禁用参数或返回值；另一个可传递 Hash，它将设置独属于参数或返回值的选项。例如，我希望只对参数作校验，而返回值不作校验，可如下设配置：
-
-```ruby
-property :name, param: { required: true }
-```
-
-再比如，我对参数不设置默认值，而返回渲染的时候提供默认值（这个例子比较少见）：
-
-```ruby
-property :age, render: { default: 18 }
-```
-
-### 如何控制不同场景下的字段
-
-上一节讲的是字段如何区分参数或返回值的情况。这是一个方面，另一方面是如何控制在不同接口下的字段返回。
-
-例如，我们定义列表接口时不需要返回详情字段，一来是列表页面用不到，另一来是详情内容会导致返回实体过大而造成网络拥塞。这时，`scope` 选项能够起到作用了。我们定义一个实体 `ArticleEntity`：
-
-```ruby
-class ArticleEntity < Meta::Entity
-  property :title
-  property :content, render: { scope: 'full' }
-end
-```
-
-> **小提示：**`scope` 选项放在 `render` 下定义，因为参数获取不需要区分场景。
-
-注意到 `content` 被限制了 scope 为 `"full"` 了，默认情况下它是不会返回的。像列表接口就可以直接渲染它：
-
-```ruby
-get '/articles' do
-  status 200 do
-    expose :articles, ref: ArticleEntity
-  end
-  action do
-    articles = Article.all
-    render :articles, articles
-  end
-end
-```
-
-而详情接口下需要返回 `content` 字段，需要明确附加一个 `scope` 为 `"full"`：
-
-```ruby
-get '/articles/:id' do
-  status 200 do
-    expose :article, ref: ArticleEntity
-  end
-  action do
-    article = Article.find(request.params['id'])
-    render :article, article, scope: "full"
-  end
-end
-```
-
-如果你认为在调用 `render` 方法时较为繁琐，好奇为什么不在声明时定义。如果你更青睐这种方式，可以在声明时控制，方法是将实体锁住。实体被锁住后就不需要在 `render` 时传递任何选项了：
-
-```ruby
-get '/articles/:id' do
-  status 200 do
-    expose :article, ref: ArticleEntity.lock_scope('full')
-  end
-  action do
-    article = Article.find(request.params['id'])
-    render :article, article
-  end
-end
-```
-
-也许在参数声明中这种方式更有效果。因为调用参数时我们无法传递 `scope` 选项，锁住是唯一的途径：
-
-```ruby
-post '/articles' do
-  params do
-    param :article, ref: ArticleEntity.lock_scope('on_create')
-  end
-  ...
-end
-
-put '/articles/:id' do
-  params do
-    param :article, ref: ArticleEntity.lock_scope('on_update')
-  end
-  ...
-end
-```
-
-### 如何渲染计算出来的结果
-
-假设现有如下实体：
-
-```ruby
-class UserEntity < Meta::Entity
-  property :first_name
-  property :last_name
-end
-```
-
-现在我们想要加一个 `full_name` 字段，它是 `first_name` 和 `last_name` 加起来的结果。这时我们可以使用 `value` 选项自己将结果计算下来：
-
-```ruby
-class UserEntity < Meta::Entity
-  property :first_name
-  property :last_name
-  property :full_name, param: false, value: lambda do |user|
-    "#{user['first_name']} #{user['last_name']}"
-  end
-end
-```
-
-> **小提示：** 设置 `param` 为 `false`，因为参数获取时没有这个字段。
-
-`value` 传递的块可以访问到执行环境，以下是一个示例：
-
-```ruby
-status 200 do
-  expose :is_admin, value: lambda { @user.admin? }
-end
-action do
-  @user = get_user
-end
-```
-
-### 参数值转化
-
-首先，我们定义实体：
-
-```ruby
-class ArticleEntity < Meta::Entity
-  property :image, 
-           type: 'string',
-           description: '客户端传递 Base64 格式的数据'
-end
-```
-
-然后我们定义路由参数：
-
-```ruby
-params do
-  param :article, ref: ArticleEntity
-end
-```
-
-由于客户端传递的参数是 Base64 格式的，我们需要在执行环境中将其转化为原本格式：
-
-```ruby
-action do
-  article_params = {
-    **params[:article],
-    image: decode_base64(params[:article][:image])
-  }
-end
-```
-
-但每个接口下都做这样的转化工作挺是繁琐，框架提供了 `convert` 选项，它用于将值转化为预期的格式：
-
-```ruby
-class ArticleEntity < Meta::Entity
-  property :image, 
-           type: 'string', 
-           description: '客户端传递 Base64 格式的数据',
-           param: {
-             convert: lambda { |value| decode_base64(value) }
-           }
-end
-```
-
-> **小提示：** 注意只应当在参数过程中做格式转换，渲染过程中做同样的转换将会出错。
-
-这样执行环境中就不需要手动进行格式转换了：
-
-```ruby
-action do
-  article_params = params[:article]
-end
-```
-
-### 多态参数和返回值
-
-定义属性时可定义多态类型，`dynamic_ref` 选项可接受一个块，它根据值来返回指定的类型：
-
-```ruby
-property :target, dynamic_ref: ->(value) {
-  # 根据 value.target_type 值返回实体类型
-  # 例如，value.target_type == 'UserEntity'，将返回 UserEntity 类
-  value.target_type.constantize
-}
-```
-
-或者接受一个 Hash，这时可提供 `one_of` 选项为文档生成提供加成：
-
-```ruby
-property :animal, dynamic_ref: {
-  one_of: [CatEntity, DogEntity, PigEntity],
-  resolve: ->(value) { value.animal_type.constantize }
-}
-```
-
-## 生成文档
-
-应用模块提供一个 `to_swagger_doc` 方法生成 Open API 规格文档，该文档可被 Swagger UI 或基于 Swagger UI 的引擎渲染。
-
-```ruby
-class DemoApp < Meta::Application
-end
-
-# 生成 JSON 格式的规格文档
-DemoApp.to_swagger_doc(
-  info: {
-    title: 'Web API 示例项目',
-    version: 'current'
-  },
-  servers: [
-    { url: 'http://localhost:9292', description: 'Web API 示例项目' }
-  ]
-)
-```
-
-其中 `info` 和 `servers` 选项是 *Open API 规格文档* 中提供。
-
-> 了解 [Open API 规格文档](https://swagger.io/resources/open-api/https://swagger.io/resources/open-api/)。
-> 
-> 了解 [Swagger UI](https://swagger.io/tools/swagger-ui/).
-
-## 全局配置
-
-### 定义默认的 `locked_scope`
-
-```ruby
-Meta.config.default_locked_scope = 'default'
-```
-
-当 `Meta::Entity` 被引用时，其没有被锁定 `scope`. 如果我们如上设定了默认的 `scope`，则
-
-```ruby
-param :user, ref: UserEntity
-```
-
-的效果等价于
-
-```ruby
-param :user, ref: UserEntity.lock_scope('default')
-```
-
-这样做对生成文档有帮助。因为我们没有锁定 `UserEntity`，则文档中它的所有属性都会被列出来，而在实际执行时却不能得到带有 `scope` 标记的字段，这样往往在造成文档和实际情况的不一致。
-
-### 定义 `JsonSchema#filter` 方法的 `user_options`
-
-```ruby
-Meta.config.json_schema_user_options = {...}
-Meta.config.json_schema_param_stage_options = {...}
-Meta.config.json_schema_render_stage_options = {...}
-```
-
-**示例一：关闭渲染时验证**
-
-渲染时不执行类型转换和数据验证：
-```ruby
-Meta.config.json_schema_render_stage_options = {
-  type_conversion: false,
-  render_validation: false
-}
-```
-
-**示例二：默认使用 `discard_missing: true` 方案**
-
-```ruby
-Meta.config.json_schema_user_options = {
-  discard_missing: true
-}
-```
-
-或仅在参数阶段使用 `discard_missing: true` 方案：
-
-```ruby
-Meta.config.json_schema_param_stage_options = {
-  discard_missing: true
-}
-```
-
-> 提示：可以传入一切 `JsonSchema#filter` 支持的选项，参考 [JsonSchema#filter 支持的选项](索引.md)。
-
-## 特殊用法举例
-
-### 路由中实体定义的特殊用法
-
-虽然推荐的方案是在实体之上包裹一个根字段，像下面这样：
-
-```ruby
-params do
-  param :user, ref: UserEntity
-end
-
-
-# 接受如下格式的数据
-{ "user": { "name": "Jim", "age": 18 } }
-```
-
-但也可以将包裹的外层字段去掉，即将 `UserEntity` 直接用在顶层：
-
-```ruby
-params ref: UserEntity
-
-
-# 接受如下格式的数据
-{ "name": "Jim", "age": 18 }
-```
-
-这个方案同时也支持数组：
-
-```ruby
-params type: 'array', ref: UserEntity
-
-# 接受如下格式的数据
-[
-  { "name": "Jim", "age": 18 },
-  { "name": "Jack", "age": 19 }
-]
-```
-
-虽然更不常见，标量值也是支持的：
-
-```ruby
-params type: 'string'
-
-# 接受字符串数据
-"foo"
-```
-
-### 完整更新和局部更新
-
-HTTP 提供了两个方法 `PUT` 和 `PATCH`，它们的语义差别体现在更新策略上。`PUT` 要求是完整更新，`PATCH` 要求是局部更新。
-
-假设我们定义参数格式为：
-
-```ruby
-params do
-  param :user do
-    param :name
-    param :age
-  end
-end
-```
-
-同时我们收到客户端的参数格式为：
-
-```json
-{
-  "user": {
-    "name": "Jim"
-  }
-}
-```
-
-`params` 方法默认的逻辑符合完整更新：
-
-```ruby
-put '/users/:id' do
-  action do
-    user = User.find(request.params['id'])
-
-    user_params = params[:user] # => { name: "Jim", age: nil }
-    user.update(user_params)
-  end
-end
-```
-
-而 `params(:discard_missing)` 将符合局部更新的逻辑：
-
-```ruby
-patch '/users/:id' do
-  action do
-    user = User.find(request.params['id'])
-
-    user_params = params(:discard_missing)[:user] # => { name: "Jim" }
-    user.update(user_params)
-  end
-end
-```
-
-> **小提示：**还有一种调用方式 `params(:raw)`，它返回无任何转换逻辑的原生参数。它与 `request.params` 的行为一致。
-
-> **大提示：**如果你是通过 `ref:` 引用一个实体定义，另一个更符合语义的方式是使用 `lock` 方法。
->
-> ```ruby
-> patch '/users/:id' do
->   params do
->     param :user, ref: UserEntity.lock(:discard_missing, true)
->   end
->   action do
->     user = User.find(params['id'])
-> 
->     user_params = params[:user] # 不需要传递 `:discard_missing` 符号了，同样也会返回 `{ name: "Jim" }`
->     user.update(user_params)
->   end
-> end
-> ```
-
-### `namespace` 中使用 `rescue_error Meta::Errors::NoMatchingRoute` 无效
-
-`Meta::Errors::NoMatchingRoute` 只在顶层捕获有效，在内部捕获无效。
-
-```ruby
-class DemoApp < Meta::Application
-  # 在此捕获有效
-  rescue_error Meta::Errors::NoMatchingRoute do |e|
-    response.status = 404
-    response.body = ["404 Not Found"]
-  end
-
-  namespace '/namespace' do
-    # 在此捕获无效
-    rescue_error Meta::Errors::NoMatchingRoute do |e|
-      response.status = 404
-      response.body = ["404 Not Found"]
-    end
-  end
-end
-```