快速入门 ¶

Yii 提供了一整套工具来简化实现 RESTful Web 服务 API 的任务。特别是，Yii 支持以下有关 RESTful API 的功能

• 使用对 活动记录 的常用 API 的支持进行快速原型设计；
• 响应格式协商（默认支持 JSON 和 XML）；
• 支持选择输出字段的自定义对象序列化；
• 正确格式化集合数据和验证错误；
• 集合分页、过滤和排序；
• 支持 HATEOAS；
• 使用正确的 HTTP 动词检查进行高效路由；
• 对 OPTIONS 和 HEAD 动词的内置支持；
• 身份验证和授权；
• 数据缓存和 HTTP 缓存；
• 速率限制；

在以下内容中，我们使用一个示例来说明如何用最少的编码量构建一组 RESTful API。

假设您想通过 RESTful API 暴露用户数据。用户数据存储在 user 数据库表中，您已经创建了 活动记录 类 app\models\User 来访问用户数据。

创建控制器 ¶

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

namespace app\controllers;

use yii\rest\ActiveController;

class UserController extends ActiveController
{
    public $modelClass = 'app\models\User';
}

控制器类继承自 yii\rest\ActiveController，它实现了一组通用的 RESTful 动作。通过将 modelClass 指定为 app\models\User，控制器知道可以使用哪个模型来获取和操作数据。

配置 URL 规则 ¶

然后，修改应用程序配置中 urlManager 组件的配置

'urlManager' => [
    'enablePrettyUrl' => true,
    'enableStrictParsing' => true,
    'showScriptName' => false,
    'rules' => [
        ['class' => 'yii\rest\UrlRule', 'controller' => 'user'],
    ],
]

以上配置主要为 user 控制器添加了一个 URL 规则，以便可以使用漂亮的 URL 和有意义的 HTTP 动词来访问和操作用户数据。

注意：Yii 会自动将控制器名称变为复数形式，以便在端点中使用（参见下面的 试用 部分）。您可以使用 yii\rest\UrlRule::$pluralize 属性来配置此行为。

启用 JSON 输入 ¶

为了让 API 接受 JSON 格式的输入数据，请配置 parsers 属性 request 应用程序组件 使用 yii\web\JsonParser 用于 JSON 输入

'request' => [
    'parsers' => [
        'application/json' => 'yii\web\JsonParser',
    ]
]

信息：以上配置是可选的。如果没有以上配置，API 将只识别 application/x-www-form-urlencoded 和 multipart/form-data 输入格式。

试用 ¶

通过以上最小的努力，您已经完成了创建用于访问用户数据的 RESTful API 的任务。您创建的 API 包括

• GET /users: 分页列出所有用户；
• HEAD /users: 显示用户列表的概述信息；
• POST /users: 创建新用户；
• GET /users/123: 返回用户 123 的详细信息；
• HEAD /users/123: 显示用户 123 的概述信息；
• PATCH /users/123 和 PUT /users/123: 更新用户 123；
• DELETE /users/123: 删除用户 123；
• OPTIONS /users: 显示关于端点 /users 的支持动词；
• OPTIONS /users/123: 显示关于端点 /users/123 的支持动词。

您可以使用 curl 命令访问您的 API，例如以下命令：

$ curl -i -H "Accept:application/json" "http://localhost/users"

HTTP/1.1 200 OK
...
X-Pagination-Total-Count: 1000
X-Pagination-Page-Count: 50
X-Pagination-Current-Page: 1
X-Pagination-Per-Page: 20
Link: <http://localhost/users?page=1>; rel=self, 
      <http://localhost/users?page=2>; rel=next, 
      <http://localhost/users?page=50>; rel=last
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

[
    {
        "id": 1,
        ...
    },
    {
        "id": 2,
        ...
    },
    ...
]

尝试将可接受的内容类型更改为 application/xml，您将看到结果以 XML 格式返回

$ curl -i -H "Accept:application/xml" "http://localhost/users"

HTTP/1.1 200 OK
...
X-Pagination-Total-Count: 1000
X-Pagination-Page-Count: 50
X-Pagination-Current-Page: 1
X-Pagination-Per-Page: 20
Link: <http://localhost/users?page=1>; rel=self, 
      <http://localhost/users?page=2>; rel=next, 
      <http://localhost/users?page=50>; rel=last
Transfer-Encoding: chunked
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <item>
        <id>1</id>
        ...
    </item>
    <item>
        <id>2</id>
        ...
    </item>
    ...
</response>

以下命令将通过发送包含 JSON 格式用户数据的 POST 请求来创建新用户

$ curl -i -H "Accept:application/json" -H "Content-Type:application/json" \
    -XPOST "http://localhost/users" \
    -d '{"username": "example", "email": "[email protected]"}'

HTTP/1.1 201 Created
...
Location: http://localhost/users/1
Content-Length: 99
Content-Type: application/json; charset=UTF-8

{"id":1,"username":"example","email":"[email protected]","created_at":1414674789,"updated_at":1414674789}

提示：您也可以通过在 Web 浏览器中输入 URL http://localhost/users 来访问您的 API。但是，您可能需要一些浏览器插件来发送特定的请求头。

如您所见，在响应头中，包含关于总计数、页数等信息。还有一些链接允许您导航到其他数据页面。例如，http://localhost/users?page=2 将为您提供用户数据的下一页。

使用 fields 和 expand 参数，您还可以指定结果中应包含哪些字段。例如，URL http://localhost/users?fields=id,email 将仅返回 id 和 email 字段。

信息：您可能已经注意到 http://localhost/users 的结果包含一些敏感字段，例如 password_hash、auth_key。您当然不希望这些出现在您的 API 结果中。您可以并且应该根据资源部分所述从结果中删除这些字段。

此外，您可以对集合进行排序，例如 http://localhost/users?sort=email 或 http://localhost/users?sort=-email。可以使用数据过滤器来过滤集合，例如 http://localhost/users?filter[id]=10 或 http://localhost/users?filter[email][like]=gmail.com。有关详细信息，请参见过滤集合部分。

自定义列表中的分页和排序 ¶

为了更改模型列表的默认分页和排序，您可以在控制器中配置yii\rest\IndexAction。例如

<?php
namespace app\controllers;

use yii\rest\ActiveController;
use yii\helpers\ArrayHelper;

class UserController extends ActiveController
{
    public $modelClass = 'app\models\User';
    
    public function actions()
    {
        return ArrayHelper::merge(parent::actions(), [
            'index' => [
                'pagination' => [
                    'pageSize' => 10,
                ],
                'sort' => [
                    'defaultOrder' => [
                        'created_at' => SORT_DESC,
                    ],
                ],
            ],
        ]);
    }
}

有关如何配置 ActiveController 的操作的更多信息，请参见扩展 ActiveController。

摘要 ¶

使用 Yii RESTful API 框架，您可以根据控制器操作来实现 API 端点，并且您可以使用控制器来组织实现单个资源类型端点的操作。

资源表示为数据模型，这些数据模型从yii\base\Model类扩展而来。如果您正在处理数据库（关系型或 NoSQL），建议您使用ActiveRecord来表示资源。

您可以使用yii\rest\UrlRule来简化路由到您的 API 端点。

虽然不是必需的，但建议您将 RESTful API 作为与 Web 前端和后端不同的独立应用程序进行开发，以便于维护。