企业官网建设流程全解析

• 后端
• Web框架

导读

在 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 状态码表达不同的语义，官方指南对此有明确归纳：

这份状态码表与 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 测试印证

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

• tests/framework/web/ErrorHandlerTest.php 直接对renderException()传入NotFoundHttpException并断言输出内容包含对应异常信息；
• tests/framework/web/ResponseTest.php 验证了setStatusCodeByException()能将异常状态码正确写入响应对象。

四、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 结构。

六、相关资源与延伸阅读

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

• 官方指南原文：本文基于 docs/guide/rest-error-handling.md（葡萄牙语版见 docs/guide-pt-BR/rest-error-handling.md）；
• 异常类：NotFoundHttpException见 framework/web/NotFoundHttpException.php，基类HttpException见 framework/web/HttpException.php；
• 错误渲染与序列化：见 framework/web/ErrorHandler.php 的renderException()与convertExceptionToArray()；
• 响应组件与事件：见 framework/web/Response.php 的send()、setStatusCodeByException()、$httpStatuses与getIsSuccessful()；
• REST 序列化器：见 framework/rest/Serializer.php 的serialize()与serializeModelErrors()；
• 测试用例：见 tests/framework/web/ErrorHandlerTest.php 与 tests/framework/web/ResponseTest.php；
• 关联指南：REST 快速入门、认证与鉴权、限流、通用错误处理。

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

• 后端
• Web框架