Yii 2 REST 错误处理完全指南:异常抛出、HTTP 状态码与自定义错误响应

原创2026-09-22 13:49:441,725 阅读
文章标签:后端Web框架

Yii 2 REST 错误处理完全指南:异常抛出、HTTP 状态码与自定义错误响应

导读

在 Yii 2 的 RESTful API 开发中,如何规范地通知客户端"请求出了什么问题"是接口设计的关键一环。本篇指南基于官方指南《Tratamento de Erros / Error Handling》整理,系统讲解 Yii 2 REST 框架的错误处理机制:通过抛出携带 HTTP 状态码的异常(如 NotFoundHttpException 对应 404)即可自动生成标准化的 JSON 错误响应,并完整列出 REST 框架使用的全部状态码语义;最后深入介绍如何借助 response 组件的 beforeSend 事件自定义错误响应格式(例如始终返回 200、将真实状态码内嵌到 JSON 结构中)。读完本文,你将掌握 Yii 2 REST 接口"异常即错误响应"的完整链路,并能在应用配置中落地自定义错误格式。

一、REST 错误处理的核心机制:抛异常即响应

在处理 RESTful API 请求时,如果用户请求存在错误,或服务器端发生了意外情况,最直接、最符合 Yii 惯例的做法就是抛出一个异常来告知调用方"出错了"。

只要你能定位错误的具体原因(例如所请求的资源不存在),就应该考虑抛出携带恰当 HTTP 状态码的异常。例如 yii\web\NotFoundHttpException 就代表 404 状态码:

use yii\web\NotFoundHttpException;

throw new NotFoundHttpException('The requested resource was not found.');

抛出之后,Yii 会自动完成以下两件事:

  1. 发送带有对应 HTTP 状态码与状态文本的响应(如 404 Not Found);
  2. 在响应体中包含异常的序列化表示。

以请求一个不存在的资源为例,实际返回的 HTTP 响应如下:

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
}

注意其中的 Content-Type: application/json —— 在 REST 场景下响应以 JSON 格式序列化,调用方可以直接从响应体中解析 status 字段与 message 字段来展示错误信息。

二、REST 框架使用的 HTTP 状态码一览

Yii 2 REST 框架在不同场景下使用以下 HTTP 状态码表达不同的语义,官方指南对此有明确归纳:

状态码 含义 典型触发场景
200 OK,一切正常 成功的 GET、PUT、PATCH 等请求
201 资源创建成功 响应 POST 请求时创建了新资源,Location 头包含指向新资源的 URL
204 请求处理成功且无响应体内容 例如 DELETE 请求
304 资源未被修改,可使用缓存版本 条件请求(If-Modified-Since / ETag)命中
400 请求格式错误 请求体携带了非法 JSON、提供了非法参数等用户侧原因
401 认证失败 未通过身份验证(参见 rest-authentication.md)
403 已认证用户无权访问该 API 端点 权限不足(参见 security-authorization.md)
404 请求的资源不存在 资源主键无效、路由不存在
405 方法不允许 请检查响应 Allow 头以获知允许的 HTTP 方法
415 不支持的媒体类型 请求的 content type 或版本号无效
422 数据验证失败 例如 POST 请求提交的数据未通过模型校验,请检查响应体中的详细错误信息
429 请求过于频繁 请求因限流(rate limiting)被拒绝(参见 rest-rate-limiting.md)
500 服务器内部错误 由程序内部错误引起

这份状态码表与 Response.php 中的 $httpStatuses 静态数组 相互印证——该数组完整维护了从 100 Continue 到 511 Network Authentication Required 的所有状态码与状态文本映射,异常名称即由此表解析得出。

三、源码级解析:异常如何变成 JSON 响应体

3.1 异常继承体系与状态码载体

以 NotFoundHttpException 为例,它的实现非常简洁(见 framework/web/NotFoundHttpException.php):

class NotFoundHttpException extends HttpException
{
    public function __construct($message = null, $code = 0, $previous = null)
    {
        parent::__construct(404, $message, $code, $previous);
    }
}

其父类 HttpException 公开了 $statusCode 属性,构造器将状态码保存下来,并通过 getName() 方法从 Response::$httpStatuses 中反查"Not Found"等人类可读的状态文本。这样一条完整的异常链(UserException → HttpException → NotFoundHttpException)同时承载了:错误信息(message)、业务错误码(code)与 HTTP 状态码(statusCode)。

3.2 错误处理器:renderException 的完整流程

当异常未被应用代码捕获时,yii\web\ErrorHandler 会接管渲染流程。其核心逻辑位于 framework/web/ErrorHandler.php 的 renderException(),关键步骤为:

  1. 重置响应对象:将 isSent、stream、data、content 全部清空,避免此前部分生成的响应数据干扰错误输出;
  2. 设置状态码:调用 $response->setStatusCodeByException($exception)。该方法的实现(见 framework/web/Response.php#L306-L315)判断异常是否为 HttpException:是则采用其 statusCode,否则一律置为 500;
  3. 按响应格式渲染:REST 场景下响应格式为 JSON,进入 convertExceptionToArray() 分支。

3.3 异常序列化数组的结构

convertExceptionToArray()(见 framework/web/ErrorHandler.php#L167-L197)决定了响应体的最终结构:

  • 基础字段(始终存在):name(异常名,如 "Not Found Exception")、message(错误信息)、code(业务错误码,通常为 0);
  • 若异常是 HttpException,额外附加 status 字段(如 404);
  • 若开启 YII_DEBUG,还会追加 type(异常类名)、file、line、stack-trace 等调试信息,方便本地开发排查;
  • 非调试模式下,若异常既不是 UserException 也不是 HttpException,会被替换为通用的 HttpException(500, 'An internal server error occurred.'),避免向客户端泄露内部实现细节。

这解释了第一节示例中 JSON 各字段的来源:name 来自 $httpStatuses[404],status 来自 $exception->statusCode。

3.4 测试印证

框架测试用例对该流程做了直接验证,可作参考:

四、422 验证错误的特殊处理:Serializer 的贡献

在表格中 422 被标注为"数据验证失败"。从源码看,REST 响应序列化器 framework/rest/Serializer.php 的 serialize() 专门处理了这种情况:当数据是 Model 实例且 hasErrors() 为真时,调用 serializeModelErrors(),它会:

  1. 将响应状态码强制设置为 422(状态文本 "Data Validation Failed.");
  2. 遍历模型 getFirstErrors(),将每个字段的错误组装为 ['field' => 字段名, 'message' => 错误信息] 数组返回。

也就是说,当你在控制器中直接返回一个带验证错误的模型时,Yii 2 REST 会自动生成类似下面的响应,无需手写任何错误处理代码:

HTTP/1.1 422 Unprocessable entity
Content-Type: application/json; charset=UTF-8

[
    {
        "field": "username",
        "message": "Username cannot be blank."
    },
    {
        "field": "email",
        "message": "Email is not a valid email address."
    }
]

五、自定义错误响应格式:beforeSend 事件实战

5.1 典型需求场景

有时默认的错误响应格式并不满足业务需要。例如:不希望通过不同的 HTTP 状态码来表达错误,而是始终返回 200 OK,把真实的 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
    }
}

5.2 实现方式:监听 response 组件的 beforeSend 事件

要实现上述效果,可以在应用配置中为 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 参数时生效,会同时改写成功与失败两类响应的格式:无论底层状态码是 200 还是 404,统一包装为 {"success": bool, "data": 原始数据} 结构,并将 HTTP 状态码强制置为 200。

5.3 底层原理:send() 与事件触发时机

为什么挂载 beforeSend 事件就能在响应发出前修改数据?因为 yii\web\Response::send()(见 framework/web/Response.php#L334-L346)的执行顺序是:

  1. 触发 self::EVENT_BEFORE_SEND(即 beforeSend,常量定义见 framework/web/Response.php#L68);
  2. 调用 prepare() 将 data 按内容协商结果格式化为 JSON/XML;
  3. 触发 EVENT_AFTER_PREPARE;
  4. sendHeaders() 发送头部、sendContent() 发送内容体。

因此事件处理器在序列化与发送之前执行,此时修改 $response->data 和 $response->statusCode 均能作用于最终输出。

另外注意示例中使用的 $response->isSuccessful:这是 Response 的只读属性,其判定逻辑为状态码落在 [200, 300) 区间。由于事件在状态码被改为 200 之前求值,success 字段能如实反映底层请求是否真的成功(如 404 时为 false),这正是该方案的精妙之处。

5.4 扩展思路

除上述"包装层"方案外,你也可以利用同一个 beforeSend 事件实现其他自定义需求,例如:

  • 统一在错误响应中追加 request_id、timestamp 等审计字段;
  • 根据客户端传入的 Accept 头切换错误信息的详细程度;
  • 为特定状态码(如 429、503)附加 Retry-After 等响应头。

需要注意的是,事件处理器中判断 $response->data !== null 是必要的:REST 中 204 No Content 等场景 data 为空,不应强行包装成 JSON 结构。

六、相关资源与延伸阅读

本文所述机制在仓库中的对应实现与文档路径如下,便于继续深入:

通过本文的机制讲解与源码佐证,你可以放心地在 Yii 2 REST 项目中采用"抛异常 + 状态码"的标准错误处理范式,并根据业务需要自由定制错误响应格式。

登录后查看全文
yii2