From 96f0a2d3dfc97890de8bde3d6937b877c54d0f4d Mon Sep 17 00:00:00 2001 From: bobchengbin Date: Mon, 17 Nov 2014 22:30:41 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=A3=E3=80=81?= =?UTF-8?q?=E6=8A=8A=E2=80=9C=E6=82=A8=E2=80=9D=E5=92=8C=E2=80=9C=E4=BD=A0?= =?UTF-8?q?=E2=80=9D=E7=BB=9F=E4=B8=80=E6=88=90=E4=BA=86=E2=80=9C=E4=BD=A0?= =?UTF-8?q?=E2=80=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/guide-zh-CN/rest-quick-start.md | 81 ++++++++++++++-------------- 1 file changed, 40 insertions(+), 41 deletions(-) diff --git a/docs/guide-zh-CN/rest-quick-start.md b/docs/guide-zh-CN/rest-quick-start.md index 16d7820f3c..17e571712e 100644 --- a/docs/guide-zh-CN/rest-quick-start.md +++ b/docs/guide-zh-CN/rest-quick-start.md @@ -1,24 +1,24 @@ 快速入门 =========== -Yii 提供了一整套用来简化实现RESTful风格的Web Service服务的API。 -特别是，Yii支持以下关于RESTful风格的API： +Yii 提供了一整套用来简化实现 RESTful 风格的 Web Service 服务的 API。 +特别是，Yii 支持以下关于 RESTful 风格的 API： -* 支持 [Active Record](db-active-record.md) 类的通用API的快速原型; -* 涉及的响应格式（在默认情况下支持JSON 和 XML）; -* 支持可选输出字段的 可定制对象序列化； -* 适当的格式的数据采集和验证错误; -* 支持 [HATEOAS](http://en.wikipedia.org/wiki/HATEOAS); -* 有适当HTTP动词检查的高效的路由; -* 内置`OPTIONS`和`HEAD`动词的支持; -* 认证和授权; -* 数据缓存和HTTP缓存; -* 速率限制; +* 支持 [Active Record](db-active-record.md) 类的通用API的快速原型 +* 涉及的响应格式（在默认情况下支持 JSON 和 XML) +* 支持可选输出字段的定制对象序列化 +* 适当的格式的数据采集和验证错误 +* 支持 [HATEOAS](http://en.wikipedia.org/wiki/HATEOAS) +* 有适当HTTP动词检查的高效的路由 +* 内置`OPTIONS`和`HEAD`动词的支持 +* 认证和授权 +* 数据缓存和HTTP缓存 +* 速率限制 如下， 我们用一个例子来说明如何用最少的编码来建立一套RESTful风格的API。 -假设你想通过RESTful风格的API来展示用户数据。用户数据被存储在用户DB表， +假设你想通过 RESTful 风格的 API 来展示用户数据。用户数据被存储在用户DB表， 你已经创建了 [[yii\db\ActiveRecord|ActiveRecord]] 类 `app\models\User` 来访问该用户数据. @@ -56,26 +56,26 @@ class UserController extends ActiveController ] ``` -上面的配置主要是为`user`控制器增加一个URL规则。这样， -用户的数据就能通过美化的URL和有意义的http动词进行访问和操作。 +上面的配置主要是为`user`控制器增加一个 URL 规则。这样， +用户的数据就能通过美化的 URL 和有意义的 http 动词进行访问和操作。 ## 尝试 随着以上所做的最小的努力，你已经完成了创建用于访问用户数据 -的RESTful风格的API。您所创建的API包括： +的 RESTful 风格的 API。你所创建的 API 包括： -* `GET /users`: 逐页列出所有用户； -* `HEAD /users`: 显示用户列表的概要信息； -* `POST /users`: 创建一个新用户； -* `GET /users/123`: 返回用户为123的详细信息; -* `HEAD /users/123`: 显示用户 123 的概述信息; -* `PATCH /users/123` and `PUT /users/123`: 更新用户123; -* `DELETE /users/123`: 删除用户123; -* `OPTIONS /users`: 显示关于末端 `/users` 支持的动词; -* `OPTIONS /users/123`: 显示有关末端 `/users/123` 支持的动词。 +* `GET /users`: 逐页列出所有用户 +* `HEAD /users`: 显示用户列表的概要信息 +* `POST /users`: 创建一个新用户 +* `GET /users/123`: 返回用户 123 的详细信息 +* `HEAD /users/123`: 显示用户 123 的概述信息 +* `PATCH /users/123` and `PUT /users/123`: 更新用户123 +* `DELETE /users/123`: 删除用户123 +* `OPTIONS /users`: 显示关于末端 `/users` 支持的动词 +* `OPTIONS /users/123`: 显示有关末端 `/users/123` 支持的动词 -> Info: Yii将在末端使用的控制器的名称自动变为复数。 +> 补充：Yii 将在末端使用的控制器的名称自动变为复数。（译注：个人感觉这里应该变为注意） 你可以访问你的API用`curl`命令如下， @@ -109,7 +109,7 @@ Content-Type: application/json; charset=UTF-8 ] ``` -试着改变可接受的内容类型为`application/xml`，你会看到结果以XML格式返回： +试着改变可接受的内容类型为`application/xml`，你会看到结果以 XML 格式返回： ``` $ curl -i -H "Accept:application/xml" "http://localhost/users" @@ -142,33 +142,32 @@ Content-Type: application/xml ``` -> Tip: 您还可以通过Web浏览器中输入URL `http://localhost/users` 来访问你的API。 - 尽管如此，你可能需要一些浏览器插件来发送特定的headers请求。 +> 技巧：你还可以通过 Web 浏览器中输入 URL `http://localhost/users` 来访问你的 API。 + 尽管如此，你可能需要一些浏览器插件来发送特定的 headers 请求。 -如你所见， 在headers响应， 有关于总数，页数的信息，等等。 -还有一些链接，让您导航到其他页面的数据. 例如， `http://localhost/users?page=2` +如你所见，在 headers 响应，有关于总数，页数的信息，等等。 +还有一些链接，让你导航到其他页面的数据。例如： `http://localhost/users?page=2` 会给你的用户数据的下一个页面。 -使用 `fields` 和 `expand` 参数， 您也可以指定哪些字段应该包含在结果内。 -例如, URL `http://localhost/users?fields=id,email` 将只返回 `id` 和 `email` 字段。 +使用 `fields` 和 `expand` 参数，你也可以指定哪些字段应该包含在结果内。 +例如：URL `http://localhost/users?fields=id,email` 将只返回 `id` 和 `email` 字段。 -> Info: 您可能已经注意到了 `http://localhost/users` 的结果包括一些敏感字段， -> 例如 `password_hash`, `auth_key`。 你肯定不希望这些出现在你的API结果中。 -> 你应该在 [Response Formatting](rest-response-formatting.md) 部分中过滤掉这些字段。 +> 补充：你可能已经注意到了 `http://localhost/users` 的结果包括一些敏感字段， +> 例如 `password_hash`, `auth_key` 你肯定不希望这些出现在你的 API 结果中。 +> 你应该在 [响应格式](rest-response-formatting.md) 部分中过滤掉这些字段。 ## 总结 -使用Yii框架的RESTful风格的API， 在控制器的操作中实现API末端， 使用 +使用 Yii 框架的 RESTful 风格的 API, 在控制器的操作中实现API末端，使用 控制器来组织末端接口为一个单一的资源类型。 从 [[yii\base\Model]] 类扩展的资源被表示为数据模型。 -如果你在使用（关系或非关系）数据库，推荐您使用 [[yii\db\ActiveRecord|ActiveRecord]] +如果你在使用（关系或非关系）数据库，推荐你使用 [[yii\db\ActiveRecord|ActiveRecord]] 来表示资源。 -你可以使用 [[yii\rest\UrlRule]] 简化路由到你的API末端。 +你可以使用 [[yii\rest\UrlRule]] 简化路由到你的 API 末端。 -虽然不是必须的，为了方便维护您的WEB前端和后端， -建议您开发接口作为一个单独的应用程序。 +为了方便维护你的WEB前端和后端，建议你开发接口作为一个单独的应用程序，虽然这不是必须的。