文字
分享

快速入门

快速入门

Yii 提供了一整套用来简化实现 RESTful 风格的 Web Service 服务的 API。 特别是,Yii 支持以下关于 RESTful 风格的 API:

  • 支持 Active Record 类的通用API的快速原型
  • 涉及的响应格式(在默认情况下支持 JSON 和 XML)
  • 支持可选输出字段的定制对象序列化
  • 适当的格式的数据采集和验证错误
  • 支持 HATEOAS
  • 有适当HTTP动词检查的高效的路由
  • 内置OPTIONSHEAD动词的支持
  • 认证和授权
  • 数据缓存和HTTP缓存
  • 速率限制

如下, 我们用一个例子来说明如何用最少的编码来建立一套RESTful风格的API。

假设你想通过 RESTful 风格的 API 来展示用户数据。用户数据被存储在用户DB表, 你已经创建了 yii\db\ActiveRecord 类app\models\User 来访问该用户数据.

创建一个控制器

首先,创建一个控制器类 app\controllers\UserController 如下,

1

2

3

4

5

6

7

8

<code style="box-sizing: border-box; font-family: Menlo, Monaco, Consolas, 'Courier New', monospace; font-size: inherit; padding: 0px; color: inherit; border-radius: 0px; white-space: pre-wrap; background-color: transparent;"><span style="box-sizing: border-box;">namespace</span> <span style="box-sizing: border-box;">app</span>\<span style="box-sizing: border-box;">controllers</span>;

 

<span style="box-sizing: border-box;">use</span> <span style="box-sizing: border-box;">yii</span>\<span style="box-sizing: border-box;">rest</span>\<span style="box-sizing: border-box;">ActiveController</span>;

 

<span style="box-sizing: border-box;"><span style="box-sizing: border-box;">class</span> <span style="box-sizing: border-box;">UserController</span> <span style="box-sizing: border-box;">extends</span> <span style="box-sizing: border-box;">ActiveController</span></span>{

    <span style="box-sizing: border-box;">public</span> <span style="box-sizing: border-box;">$modelClass</span> = <span style="box-sizing: border-box;">'app\models\User'</span>;

}

</code>

控制器类扩展自 yii\rest\ActiveController。通过指定 yii\rest\ActiveController::modelClass 作为 app\models\User, 控制器就能知道使用哪个模型去获取和处理数据。

配置URL规则

然后,修改有关在应用程序配置的urlManager组件的配置:

1

2

3

4

5

6

7

8

9

<code style="box-sizing: border-box; font-family: Menlo, Monaco, Consolas, 'Courier New', monospace; font-size: inherit; padding: 0px; color: inherit; border-radius: 0px; white-space: pre-wrap; background-color: transparent;"><span style="box-sizing: border-box;">'urlManager'</span> => [

    <span style="box-sizing: border-box;">'enablePrettyUrl'</span> => <span style="box-sizing: border-box;">true</span>,

    <span style="box-sizing: border-box;">'enableStrictParsing'</span> => <span style="box-sizing: border-box;">true</span>,

    <span style="box-sizing: border-box;">'showScriptName'</span> => <span style="box-sizing: border-box;">false</span>,

    <span style="box-sizing: border-box;">'rules'</span> => [

        [<span style="box-sizing: border-box;">'class'</span> => <span style="box-sizing: border-box;">'yii\rest\UrlRule'</span>, <span style="box-sizing: border-box;">'controller'</span> => <span style="box-sizing: border-box;">'user'</span>],

    ],

]

</code>

上面的配置主要是为user控制器增加一个 URL 规则。这样, 用户的数据就能通过美化的 URL 和有意义的 http 动词进行访问和操作。

尝试

随着以上所做的最小的努力,你已经完成了创建用于访问用户数据 的 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 支持的动词

补充:Yii 将在末端使用的控制器的名称自动变为复数。(译注:个人感觉这里应该变为注意)

你可以访问你的API用curl命令如下,

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

<code style="box-sizing: border-box; font-family: Menlo, Monaco, Consolas, 'Courier New', monospace; font-size: inherit; padding: 0px; color: inherit; border-radius: 0px; white-space: pre-wrap; background-color: transparent;">$ curl -i -H <span style="box-sizing: border-box;">"Accept:application/json"</span> <span style="box-sizing: border-box;">"http://localhost/users"</span>

 

HTTP/<span style="box-sizing: border-box;">1.1</span> <span style="box-sizing: border-box;">200</span> OK

Date: Sun, <span style="box-sizing: border-box;">02</span> Mar <span style="box-sizing: border-box;">2014</span> <span style="box-sizing: border-box;">05</span>:<span style="box-sizing: border-box;">31</span>:<span style="box-sizing: border-box;">43</span> GMT

Server: Apache/<span style="box-sizing: border-box;">2.2</span><span style="box-sizing: border-box;">.26</span> (Unix) DAV/<span style="box-sizing: border-box;">2</span> PHP/<span style="box-sizing: border-box;">5.4</span><span style="box-sizing: border-box;">.20</span> mod_ssl/<span style="box-sizing: border-box;">2.2</span><span style="box-sizing: border-box;">.26</span> OpenSSL/<span style="box-sizing: border-box;">0.9</span><span style="box-sizing: border-box;">.8</span>y

X-Powered-By: PHP/<span style="box-sizing: border-box;">5.4</span><span style="box-sizing: border-box;">.20</span>

X-Pagination-Total-Count: <span style="box-sizing: border-box;">1000</span>

X-Pagination-Page-Count: <span style="box-sizing: border-box;">50</span>

X-Pagination-Current-Page: <span style="box-sizing: border-box;">1</span>

X-Pagination-Per-Page: <span style="box-sizing: border-box;">20</span>

Link: <http:<span style="box-sizing: border-box;">//localhost/users?page=1>; rel=self, </span>

      <http:<span style="box-sizing: border-box;">//localhost/users?page=2>; rel=next, </span>

      <http:<span style="box-sizing: border-box;">//localhost/users?page=50>; rel=last</span>

Transfer-Encoding: chunked

Content-Type: application/json; charset=UTF-<span style="box-sizing: border-box;">8</span>

 

[

    {

        <span style="box-sizing: border-box;">"id"</span>: <span style="box-sizing: border-box;">1</span>,

        ...

    },

    {

        <span style="box-sizing: border-box;">"id"</span>: <span style="box-sizing: border-box;">2</span>,

        ...

    },

    ...

]

</code>

试着改变可接受的内容类型为application/xml,你会看到结果以 XML 格式返回:

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

<code style="box-sizing: border-box; font-family: Menlo, Monaco, Consolas, 'Courier New', monospace; font-size: inherit; padding: 0px; color: inherit; border-radius: 0px; white-space: pre-wrap; background-color: transparent;">$ curl -i -H "Accept:application/xml" "http://localhost/users"

 

HTTP/1.1 200 OK

Date: Sun, 02 Mar 2014 05:31:43 GMT

Server: Apache/2.2.26 (Unix) DAV/2 PHP/5.4.20 mod_ssl/2.2.26 OpenSSL/0.9.8y

X-Powered-By: PHP/5.4.20

X-Pagination-Total-Count: 1000

X-Pagination-Page-Count: 50

X-Pagination-Current-Page: 1

X-Pagination-Per-Page: 20

Link: <span style="box-sizing: border-box;"><<span style="box-sizing: border-box;">http:</span>//<span style="box-sizing: border-box;">localhost</span>/<span style="box-sizing: border-box;">users</span>?<span style="box-sizing: border-box;">page</span>=<span style="box-sizing: border-box;">1</span>></span>; rel=self,

      <span style="box-sizing: border-box;"><<span style="box-sizing: border-box;">http:</span>//<span style="box-sizing: border-box;">localhost</span>/<span style="box-sizing: border-box;">users</span>?<span style="box-sizing: border-box;">page</span>=<span style="box-sizing: border-box;">2</span>></span>; rel=next,

      <span style="box-sizing: border-box;"><<span style="box-sizing: border-box;">http:</span>//<span style="box-sizing: border-box;">localhost</span>/<span style="box-sizing: border-box;">users</span>?<span style="box-sizing: border-box;">page</span>=<span style="box-sizing: border-box;">50</span>></span>; rel=last

Transfer-Encoding: chunked

Content-Type: application/xml

 

<span style="box-sizing: border-box;"><?xml version="1.0" encoding="UTF-8"?></span><span style="box-sizing: border-box;"><<span style="box-sizing: border-box;">response</span>></span>

    <span style="box-sizing: border-box;"><<span style="box-sizing: border-box;">item</span>></span>

        <span style="box-sizing: border-box;"><<span style="box-sizing: border-box;">id</span>></span>1<span style="box-sizing: border-box;"></<span style="box-sizing: border-box;">id</span>></span>

        ...

    <span style="box-sizing: border-box;"></<span style="box-sizing: border-box;">item</span>></span>

    <span style="box-sizing: border-box;"><<span style="box-sizing: border-box;">item</span>></span>

        <span style="box-sizing: border-box;"><<span style="box-sizing: border-box;">id</span>></span>2<span style="box-sizing: border-box;"></<span style="box-sizing: border-box;">id</span>></span>

        ...

    <span style="box-sizing: border-box;"></<span style="box-sizing: border-box;">item</span>></span>

    ...

<span style="box-sizing: border-box;"></<span style="box-sizing: border-box;">response</span>></span></code>

技巧:你还可以通过 Web 浏览器中输入 URL http://localhost/users 来访问你的 API。 尽管如此,你可能需要一些浏览器插件来发送特定的 headers 请求。

如你所见,在 headers 响应,有关于总数,页数的信息,等等。 还有一些链接,让你导航到其他页面的数据。例如:http://localhost/users?page=2 会给你的用户数据的下一个页面。

使用 fields 和 expand 参数,你也可以指定哪些字段应该包含在结果内。 例如:URL http://localhost/users?fields=id,email 将只返回 id 和 email 字段。

补充:你可能已经注意到了 http://localhost/users 的结果包括一些敏感字段, 例如 password_hashauth_key 你肯定不希望这些出现在你的 API 结果中。 你应该在 响应格式 部分中过滤掉这些字段。

总结

使用 Yii 框架的 RESTful 风格的 API, 在控制器的操作中实现API末端,使用 控制器来组织末端接口为一个单一的资源类型。

从 yii\base\Model 类扩展的资源被表示为数据模型。 如果你在使用(关系或非关系)数据库,推荐你使用 yii\db\ActiveRecord 来表示资源。

你可以使用 yii\rest\UrlRule 简化路由到你的 API 末端。

为了方便维护你的WEB前端和后端,建议你开发接口作为一个单独的应用程序,虽然这不是必须的。