错误处理 ¶

在处理 RESTful API 请求时，如果用户请求中存在错误，或者服务器上发生了意外情况，您可以简单地抛出异常来通知用户发生了错误。如果您能识别错误原因（例如，请求的资源不存在），您应该考虑抛出一个异常，并附带一个适当的 HTTP 状态代码（例如，yii\web\NotFoundHttpException 表示 404 状态代码）。Yii 将发送带有相应 HTTP 状态代码和文本的响应。Yii 还将在响应正文中包含异常的序列化表示。例如

HTTP/1.1 404 Not Found
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
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

{
    "name": "Not Found Exception",
    "message": "The requested resource was not found.",
    "code": 0,
    "status": 404
}

以下列表总结了 Yii REST 框架使用的 HTTP 状态代码

• 200：OK。一切按预期工作。
• 201：响应 POST 请求成功创建了一个资源。Location 标头包含指向新创建资源的 URL。
• 204：请求已成功处理，响应不包含任何正文内容（例如，DELETE 请求）。
• 304：资源未修改。您可以使用缓存版本。
• 400：错误的请求。这可能是由用户采取的各种操作造成的，例如在请求正文中提供无效的 JSON 数据，提供无效的操作参数等。
• 401：身份验证失败。
• 403：已认证的用户无权访问指定的 API 端点。
• 404：请求的资源不存在。
• 405：方法不允许。请检查 Allow 标头以查看允许的 HTTP 方法。
• 415：不支持的媒体类型。请求的内容类型或版本号无效。
• 422：数据验证失败（例如，响应 POST 请求）。请检查响应正文以获取详细的错误消息。
• 429：太多请求。由于速率限制，请求被拒绝。
• 500：内部服务器错误。这可能是由内部程序错误造成的。

自定义错误响应 ¶

有时您可能希望自定义默认的错误响应格式。例如，您不希望依靠使用不同的 HTTP 状态来指示不同的错误，而是希望始终使用 200 作为 HTTP 状态，并将实际的 HTTP 状态代码作为响应中 JSON 结构的一部分，如下所示，

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
Transfer-Encoding: chunked
Content-Type: application/json; charset=UTF-8

{
    "success": false,
    "data": {
        "name": "Not Found Exception",
        "message": "The requested resource was not found.",
        "code": 0,
        "status": 404
    }
}

为了实现这个目标，您可以在应用程序配置中响应response组件的beforeSend事件

return [
    // ...
    'components' => [
        'response' => [
            'class' => 'yii\web\Response',
            'on beforeSend' => function ($event) {
                $response = $event->sender;
                if ($response->data !== null && Yii::$app->request->get('suppress_response_code')) {
                    $response->data = [
                        'success' => $response->isSuccessful,
                        'data' => $response->data,
                    ];
                    $response->statusCode = 200;
                }
            },
        ],
    ],
];

上面的代码将重新格式化响应（成功和失败的响应），如suppress_response_code作为GET参数传递时所解释的。