meta-api 0.0.1

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

@@ -0,0 +1,1199 @@
+# 教程
+
+现有的 Web API 框架并不关注文档的问题，文档往往是作为插件挂载到框架上的。但是，文档和业务实现并不需要割裂开，它们在很大程度上应该是耦合在一起的。比方说，某个接口我定义了参数如此，就该自动生成一致的文档向前端告知；同样，当我提供了文档是如此后，我的接口实现就改自动地约束为这样实现。
+
+Meta 框架（暂定名）天生就是将文档和实现统一起来的，并始终致力于此（如果真的有什么不一致或者不到位的地方，那只能说框架实现上尚有欠缺，并不能从思想上说本该如此）。Meta 框架与 Swagger 合作，致力于产生符合 Restful 和社区规范的文档格式。它提供了几乎完整的描述接口信息的宏命令，并且在描述接口的同时就能基本实现接口的一些约束，其中最重要的莫过于对参数和返回值的声明。
+
+## 准备工作
+
+在正式阅读本教程之前，有一些*准备工作*需要提前了解的。
+
+### 一些限制
+
+在正式介绍框架能力之前，我先声明一下框架的约束。设定这些约束，主要是因为框架开发尚处于初期阶段，而且精力有限，因此将框架的完成度限定在更小的范围内。
+
+1. **只接受格式为 `application/json` 的请求参数，并且响应实体的格式一律为 `application/json`.**
+   
+   这在当前的环境下并不算太大的限制，如果你是致力于新项目的开发的话。但是，如果你处理旧项目，并且要求格式为 `application/json` 之外的格式，如 `application/xml`，则框架目前是无能为力的。
+   
+   这中限制只包括请求参数的实体，诸如路径里的参数、或 query 中的参数依然可用，不受该限制。
+
+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)）。
+
+### 教程脉络
+
+首先，你将了解定义路由的全部知识。你从其他框架学习的经验也同样适用于本框架，如嵌套路由、before/after 钩子、异常拦截等、以及模块共享和复用等。
+
+然后，你将了解路由的内部如何定义。换句话说，你该如何具体地*描述*一个接口。一般来说，我们需要描述接口的标题、详述、标签、参数和返回值。
+
+接下来，我们将深入参数和返回值的定义。虽然说前面已经提到参数和返回值的知识，但仅覆盖最简单同时也是最常用的场景。参数和返回值的知识实在是太大了，有必要专门划出一个章节来介绍它。这里提一下，参数和返回值在 Meta 框架里都统一为一个叫做实体的概念，因此你只需要学会定义一种就能够同时定义两者了。
+
+最后，将是一个生成文档的方法。虽然它很简单，仅仅是一个方法，但它如此重要以至于我不得不专门划出一个章节来强调它的重要性。说实话将这块内容放在最后我有点不太满意，它是如此重要，开篇就该提到。
+
+## 模块和路由定义
+
+*（我抛弃了 Rack 和中间件的知识，如果你知道它将更好了）*
+
+在 Meta 中，`Meta::Application` 类用来定义一个模块。一个模块同时也是一个应用，将它挂载在 Rack 下可以直接作为一个服务运行。我将它称为模块主要是因为它可以复用（后面你将了解到使用 `apply` 方法复用一个模块）。
+
+我们先看一下最简单的 `Meta::Application` 实例：
+
+```ruby
+class DemoApp < Meta::Application
+  get do
+    title '应用的根路径'
+    action do
+      response.body = ["Hello, world!"]
+    end
+  end
+end
+```
+
+*将它挂载在 Rack 下并访问 `http://localhost:9292` 你将看到效果。*
+
+这里，我们只是用 `get` 方法简单地定义了一个 `get /`  路由，并定义了该路由下的标题和实现。该实现没有用到 Meta 框架提供的参数和返回值的概念，只是简单地操纵原生 Rack Response 对象返回一个纯文本格式。
+
+### 路由定义
+
+除了 `get` 之外，我们还支持 `post`、`put`、`patch`、`delete` 四个方法。同时后面可跟一个路径表示路的路径：
+
+```ruby
+class DemoApp < Meta::Application
+  post do
+    # ...
+  end
+
+  put '/foo' do
+    # ...
+  end
+
+  patch '/bar' do
+    # ...
+  end
+
+  delete '/foo/bar' do
+    # ...
+  end
+end
+```
+
+以上方法只是 `route(path, method, &block)` 的简写，例如 `put '/foo'` 可以完整地写为 `route '/foo', :put`.
+
+### 路径定义
+
+路径中可以包括参数：
+
+- `/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']` 。（注意，方括号内一定得是字符串）
+
+如果你不需要后续访问到参数，可以忽略命名。不过我认为加个名字语义上更加友好，尽管你不必用到。
+
+- `/foo/:`
+- `/foo/*`
+
+在定义参数时要学会不拘一格，试想一下以下的路径定义将匹配哪些：
+
+- `/foo/:id/bar`
+- `/foo/*/bar`
+
+### 嵌套路由
+
+用 `route` 方式定义的路由是不支持嵌套的。有一个专门为定义嵌套路由而存在的命令：`namespace`.
+
+```ruby
+class DemoApp < Meta::Application
+  namespace '/user' do
+    get do
+      title '获取用户详情'
+    end
+
+    put do
+      title '更新用户详情'
+    end
+  end
+end
+```
+
+### before/after 钩子
+
+*（如果不涉及到钩子和异常拦截，嵌套路由将毫无意义。）*
+
+正如名字所表达的那样，`before` 就是 before 钩子，`after` 就是 after 钩子。将以上例子加上 `before` 钩子将如下：
+
+```ruby
+class DemoApp < Meta::Application
+  namespace '/user' do
+    before do
+      @user = get_user
+    end
+
+    get do
+      title '获取用户详情'
+    end
+
+    put do
+      title '更新用户详情'
+    end
+  end
+end
+```
+
+### 异常拦截
+
+在 `namespace` 中使用 `rescue_error` 拦截异常。
+
+```ruby
+class DemoApp < Meta::Application
+  namespace '/user' do
+    rescue_error RecordNotFound do |e|
+      response.status = 404
+      response.body = ["所访问的资源不存在"]
+    end
+  end
+end
+```
+
+### 关于嵌套的进一步说明
+
+钩子只在当前作用域和它的子作用域下起作用，父级作用域不会起作用。
+
+```ruby
+class DemoApp < Meta::Application
+  namespace '/foo' do
+    before do
+      @foo = 'foo'
+    end
+
+    get do
+      action do
+        p @foo # 'foo'
+        p @bar # nil
+      end
+    end
+
+    namespace '/bar' do
+      before do
+          @foo = 'foo'
+      end
+
+      get do
+        action do
+          p @foo # 'foo'
+          p @bar # 'bar'
+        end
+      end
+    end
+  end
+end
+```
+
+异常拦截先拦截子作用域；如果拦截失败则继续在父作用域下拦截。
+
+```ruby
+class DemoApp < Meta::Application
+  namespace '/foo' do
+    rescue_error ErrorOne do
+      # 它将捕获 '/foo' 路由下的异常
+    end
+
+    namespace '/bar' do
+      rescue_error ErrorTwo do
+        # 它将捕获 '/foo/bar' 路由下的异常
+      end
+    end
+  end
+end
+```
+
+### 模块
+
+`Meta::Application` 可以像 `namespace` 一样，定义路由、设置 before/after 钩子、拦截异常等。将以上例子里 `/foo` 的部分抽成一个模块如下：
+
+```ruby
+class Foo < Meta::Application
+  rescue_error ErrorOne do
+    # 它将捕获 '/foo' 路由下的异常
+  end
+
+  namespace '/bar' do
+    rescue_error ErrorTwo do
+      # 它将捕获 '/foo/bar' 路由下的异常
+    end
+  end
+end
+```
+
+为达到同样的效果，我们可以在 `DemoApp` 下应用这个模块：
+
+```ruby
+class DemoApp < Meta::Application
+  namespace '/foo' do
+    apply Foo
+  end
+end
+```
+
+模块应用最常用的场景是将接口分离到单独的文件中定义。这里我贴出我在一个实际项目中的模块划分：
+
+```ruby
+class OpenAPIApp < Meta::Application
+  apply API::Logins
+  apply API::Users
+  apply API::Organizations
+  apply API::Projects
+  apply API::Versions
+  apply API::Members
+end
+```
+
+## 路由内部定义
+
+现在我们关注路由内部细节的定义，包括标题、描述、参数、返回值乃至于如何实现业务逻辑等。我们知道，路由是通过 `route` 方法（以及它的一系列便捷方法 `get`、`post` 等），也就是说我们现在开始关注 `route` 方法内部能定义什么。
+
+本来想大书特书，结果发现以下代码示例便能将用到的宏命令列举完毕。
+
+```ruby
+route '/user', :put do
+  title '更新用户'
+  description '接口的详细描述'
+  tags ['User'] # 传递一个数组
+  params do
+    # 定义参数
+    param :user do
+      param :name
+      param :age
+    end
+  end
+  status 200 do
+    # 定义返回值，其中 200 是状态码
+    expose :user do
+      expose :name
+      expose :age
+    end
+  end
+  action do
+    # 业务逻辑在这里实现，通过 params 方法访问参数，render 方法渲染实体
+    user = get_user
+    user.update!(params[:user])
+    render :user, user
+  end
+end
+```
+
+### `meta` 命令
+
+除 `action` 之外，`route` 块下其余的命令都与文档的生成相关。它们都可以被汇总到一个称为 `meta` 的块内：
+
+```ruby
+route '/user', :put do
+  meta do
+    title '更新用户'
+    description '接口的详细描述'
+    tags ['User'] # 传递一个数组
+    params do
+      # 定义参数
+    end
+    status 200 do
+      # 定义返回值
+    end
+  end
+  action do
+    # 业务逻辑仍在这里实现
+  end
+end
+```
+
+### `namespace` 下的 `meta` 命令
+
+`namespace` 下可以也定义 `meta` 块，它可以定义接口声明的公共部分，应用到它的子路由下：
+
+```ruby
+namespace '/user/:id' do
+  meta do
+    # 在 namespace 下定义 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 框架在底层不区分参数和返回值，它们都统一为“实体”的概念。因此，当涉及到语法细节时，在参数、返回值、实体内都是一致的。
+
+可以说，有关实体的定义，是 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
+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` 内部使用 `using` 引用这个实体：
+
+```ruby
+params do
+  param :user, using: UserEntity
+end
+
+status 200 do
+  expose :user, using: UserEntity
+end
+```
+
+我们通过继承 `Meta::Entity` 类定义了实体并到处引用，从而简化了代码。这在实践中是推荐的方案。鉴于参数、返回值、实体的定义语法是完全一致的，故而接下来我们将重点进入实体的讲解环节。希望读者清楚的是，以上参数介绍的语法在实体定义中是完全可用的；并且，接下来有关实体的语法也能完全运用到单独的参数和返回值定义块中。
+
+> **小提示：**我们在 `params` 中用 `param` 命令定义参数字段，在 `status` 中用 `expose` 命令定义返回值字段，而在实体定义中这个命令变成了 `property`. 这里需要阐明的是，用 `param`、`expose` 还是 `property` 只是习惯的不同而已，它们的行为都是一致的并且能够混用。例如，你完全可以在 `params` 和 `status` 中一律使用 `property` 命令：
+> 
+> ```ruby
+> params do
+>   property :user, using: UserEntity
+> end
+> 
+> status 200 do
+>   property :user, using: UserEntity
+> end
+> ```
+
+### 实体定义的其他介绍
+
+`param` 和 `expose` 的只会作用到同层的字段，不会作用到实体内部。
+
+数组内部也可以引用实体，只要在字段上加上 `type: "array"` 即可：
+
+```ruby
+params do
+  param :users, type: "array", using: 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, using: 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, using: 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, using: 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, using: ArticleEntity.lock_scope('on_create')
+  end
+  ...
+end
+
+put '/articles/:id' do
+  params do
+    param :article, using: 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, using: 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
+```
+
+## 生成文档
+
+应用模块提供一个 `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/).
+
+## 特殊用法举例
+
+##
+
+### 路由中实体定义的特殊用法
+
+虽然推荐的方案是在实体之上包裹一个根字段，像下面这样：
+
+```ruby
+params do
+  param :user, using: UserEntity
+end
+
+
+# 接受如下格式的数据
+{ "user": { "name": "Jim", "age": 18 } }
+```
+
+但也可以将包裹的外层字段去掉，即将 `UserEntity` 直接用在顶层：
+
+```ruby
+params using: UserEntity
+
+
+# 接受如下格式的数据
+{ "name": "Jim", "age": 18 }
+```
+
+这个方案同时也支持数组：
+
+```ruby
+params type: 'array', using: 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` 的行为一致。
+
+> **大提示：**如果你是通过 `using:` 引用一个实体定义，另一个更符合语义的方式是使用 `lock` 方法。
+>
+> ```ruby
+> patch '/users/:id' do
+>   params do
+>     param :user, using: 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
+```