Yii 2 REST API 错误处理完整指南:异常驱动的 HTTP 错误响应与自定义格式
Yii 2 REST API 错误处理完整指南:异常驱动的 HTTP 错误响应与自定义格式
RESTful API 请求处理过程中,无论是用户请求本身有误,还是服务端发生了意外状况,Yii 2 都推荐以「抛出异常」的方式向客户端通知错误;框架会自动将异常转换成对应的 HTTP 状态码、状态文本以及序列化到响应体中的错误详情。本文以官方指南(docs/guide-ru/rest-error-handling.md)为主线,结合仓库源码(framework/web/ErrorHandler.php、framework/web/HttpException.php 等)深入讲解异常如何被转换为 REST 错误响应、Yii REST 框架使用的全部 HTTP 状态码语义,以及如何通过 beforeSend 事件自定义错误响应格式。读完本文,你将能够在自己的 Yii 2 应用中精确控制 API 的错误输出,并理解其底层调用链。
一、核心思想:用异常驱动错误响应
当 RESTful API 请求处理过程中出现错误时,最直接、最符合 Yii 2 设计哲学的做法是直接抛出异常,让框架替你完成后续的一切:
- 若能明确错误的具体原因(例如请求的资源不存在),应抛出携带正确 HTTP 状态码的异常,例如
yii\web\NotFoundHttpException对应 404; - Yii 会据此发送带有对应 HTTP 状态码与状态文本的响应;
- 同时在响应体中包含异常的序列化表示(默认格式为 JSON)。
以 404 为例,向一个不存在的资源发送请求,客户端实际收到的响应形如:
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
}
这个响应体结构并非凭空产生,而是由 framework/web/ErrorHandler.php 中的 convertExceptionToArray() 方法生成的:
name:异常的人类可读名称(HttpException通过getName()从 framework/web/HttpException.php 映射Response::$httpStatuses得到);message:异常消息;code:异常的内部错误码;status:仅当异常是HttpException时输出,取自其statusCode属性(framework/web/HttpException.php)。
二、如何抛出携带 HTTP 状态码的异常
2.1 最简用法:内置异常类
Yii 为每个常用 HTTP 状态码都预置了对应的异常子类,使用时无需指定状态码,构造时只需传错误消息:
use yii\web\NotFoundHttpException;
// 在控制器或 REST action 中
if ($model === null) {
throw new NotFoundHttpException('The requested resource was not found.');
}
查看 framework/web/NotFoundHttpException.php 的构造函数,可见它在内部固定调用 parent::__construct(404, $message, $code, $previous)——404 状态码被固化在异常类中,这正是「抛出异常即响应 404」的底层依据。
2.2 通用用法:HttpException
若内置类不满足需求,可直接使用基类 yii\web\HttpException,第一个参数为 HTTP 状态码:
use yii\web\HttpException;
if ($item === null) { // 条目不存在
throw new HttpException(404, 'The requested Item could not be found.');
}
framework/web/HttpException.php 的构造函数会将传入的状态码保存到公开属性 $statusCode,随后由错误处理器读取。该异常继承自 yii\base\UserException,意味着它在生产模式下也会向用户展示消息(详见下文第七节)。
2.3 框架如何把异常变成状态码
抛出异常后,framework/web/ErrorHandler.php 的 renderException() 会调用 Response::setStatusCodeByException($exception) 设置状态码。framework/web/Response.php 的实现如下:
- 若异常是
HttpException实例,则状态码取$e->statusCode; - 否则一律使用
500。
三、Yii REST 框架使用的 HTTP 状态码速查表
官方指南给出了 Yii REST 框架中实际使用到的全部状态码语义,完整整理如下:
| 状态码 | 含义 | 典型场景 |
|---|---|---|
200 |
OK,一切按预期工作 | 查询/读取资源成功 |
201 |
资源创建成功 | 响应 POST 请求创建资源,Location 响应头包含新资源 URL |
204 |
请求处理成功且响应体为空 | 如 DELETE 请求 |
304 |
资源未修改 | 可使用缓存版本(配合条件请求) |
400 |
错误请求 | 请求体中的 JSON 数据非法、action 参数错误等客户端问题 |
401 |
认证失败 | 未提供有效凭据 |
403 |
已认证但无权限 | 认证用户无权访问指定 API 端点 |
404 |
请求的资源不存在 | 资源查找失败 |
405 |
方法不被允许 | 查看响应头 Allow 确认允许的 HTTP 方法 |
415 |
不支持的媒体类型 | 请求的内容类型或版本号无效 |
422 |
数据校验失败 | 如响应 POST 请求时的字段校验错误,详情见响应体 |
429 |
请求过于频繁 | 因限流(rate limiting)拒绝请求 |
500 |
服务器内部错误 | 程序内部错误导致 |
3.1 状态码与内置异常类的一一映射
为便于查阅,现将状态码与仓库中对应的异常类(均位于 framework/web 目录)对照如下:
| 状态码 | 异常类 | 文件 |
|---|---|---|
| 400 | BadRequestHttpException |
framework/web/BadRequestHttpException.php |
| 401 | UnauthorizedHttpException |
framework/web/UnauthorizedHttpException.php |
| 403 | ForbiddenHttpException |
framework/web/ForbiddenHttpException.php |
| 404 | NotFoundHttpException |
framework/web/NotFoundHttpException.php |
| 405 | MethodNotAllowedHttpException |
framework/web/MethodNotAllowedHttpException.php |
| 406 | NotAcceptableHttpException |
framework/web/NotAcceptableHttpException.php |
| 409 | ConflictHttpException |
framework/web/ConflictHttpException.php |
| 410 | GoneHttpException |
framework/web/GoneHttpException.php |
| 415 | UnsupportedMediaTypeHttpException |
framework/web/UnsupportedMediaTypeHttpException.php |
| 422 | UnprocessableEntityHttpException |
framework/web/UnprocessableEntityHttpException.php |
| 429 | TooManyRequestsHttpException |
framework/web/TooManyRequestsHttpException.php |
| 500 | ServerErrorHttpException |
framework/web/ServerErrorHttpException.php |
这些类结构完全一致,仅固化各自的状态码常量。以 framework/web/TooManyRequestsHttpException.php 为例,其构造函数内部即 parent::__construct(429, ...),配合 REST 限流(rate limiting)机制使用(参见 docs/guide-ru/rest-rate-limiting.md)。所有状态码的文本描述集中定义在 framework/web/Response.php 的静态属性 $httpStatuses 中。
四、自定义错误响应格式
4.1 典型需求:始终返回 200,把真实状态码放进 JSON
某些业务场景(例如兼容老旧客户端、需要保持统一的网关契约)希望无论成功还是失败都返回 HTTP 200,而把真实状态码作为 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
}
}
注意这里真实状态码 404 被保留在了 data.status 字段中,而外层 HTTP 状态是 200。
4.2 实现方式:监听 response 组件的 beforeSend 事件
只需在应用配置(config/web.php)中给 response 组件挂一个 beforeSend 事件处理器,即可在响应发送前改写其结构与状态码:
return [
// ...
'components' => [
'response' => [
'class' => 'yii\web\Response',
'on beforeSend' => function ($event) {
$response = $event->sender;
if ($response->data !== null && !empty(Yii::$app->request->get('suppress_response_code'))) {
$response->data = [
'success' => $response->isSuccessful,
'data' => $response->data,
];
$response->statusCode = 200;
}
},
],
],
];
上述代码的行为规则是:当请求携带 GET 参数 suppress_response_code 时,无论请求成功还是失败,都会将响应重排为 {success, data} 结构,并把 HTTP 状态码强制改为 200。其中:
$response->isSuccessful是布尔值,由 framework/web/Response.php 的getIsSuccessful()计算:状态码落在200–299区间即为true,因此 404 错误会被如实标记为false;$response->data即第三节所述的异常序列化数组,由 JSON 格式化器最终编码输出。
4.3 事件触发时机:从源码看调用链
为什么这段代码能生效?查看 framework/web/Response.php 的 send() 方法:
public function send()
{
if ($this->isSent) {
return;
}
$this->trigger(self::EVENT_BEFORE_SEND); // 在这里触发 beforeSend
$this->prepare(); // 按格式化器(JSON/XML/HTML...)编码 data
$this->trigger(self::EVENT_AFTER_PREPARE);
$this->sendHeaders();
$this->sendContent();
$this->trigger(self::EVENT_AFTER_SEND);
$this->isSent = true;
}
beforeSend(常量 EVENT_BEFORE_SEND,见 framework/web/Response.php)在 prepare() 之前触发,因此此时修改 $response->data 与 $response->statusCode 都会在随后生效。而 prepare() 会根据响应的 format 属性调用对应格式化器——对于 REST API 默认的 JSON 格式,由 framework/web/JsonResponseFormatter.php 的 formatJson() 将 $response->data 经 Json::encode() 编码为响应内容。
4.4 一个注意事项:判定条件
官方英文版指南中的判断条件是 $response->data !== null && Yii::$app->request->get('suppress_response_code'),俄语版使用了更严谨的 !empty(...) 写法(docs/guide-ru/rest-error-handling.md),二者实际效果等价:仅当响应确实携带数据(避免空响应被无意义包装),且客户端显式传入 suppress_response_code 参数时才改写格式。如果不希望依赖客户端传参,也可以直接移除该条件,对所有响应一律使用该包装结构。
五、错误处理链路:从异常抛出到响应送达
为了让你对整套机制有整体把握,这里梳理从「抛出异常」到「客户端收到响应」的完整调用链(源码依据:framework/base/ErrorHandler.php):
- 注册:应用启动时,
ErrorHandler::register()(framework/base/ErrorHandler.php)调用set_exception_handler()与set_error_handler(),将未捕获异常与 PHP 错误统一接管; - 捕获:未捕获异常进入
handleException()(framework/base/ErrorHandler.php),记录异常并清空已输出内容; - 日志:
logException()以yii\web\HttpException:404这样的分类写入日志(framework/base/ErrorHandler.php),方便按状态码检索错误; - 渲染:
renderException()(framework/web/ErrorHandler.php)重置 response 对象 → 通过setStatusCodeByException()设置状态码 → 按格式输出:- HTML 格式:渲染错误视图(
errorView/exceptionView); - RAW 格式:输出纯文本异常;
- 其他格式(JSON/XML 等 REST 场景):调用
convertExceptionToArray()序列化异常为数组;
- HTML 格式:渲染错误视图(
- 发送:
Response::send()触发beforeSend事件 → 格式化器编码 → 发送头部与内容。
六、调试模式与生产模式的响应差异
convertExceptionToArray() 对调试(YII_DEBUG)与生产环境做了差异处理,理解这一点对排查线上问题至关重要(framework/web/ErrorHandler.php):
生产模式(YII_DEBUG 为 false)下:
- 若异常不是
UserException或HttpException,会被替换为统一的HttpException(500, 'An internal server error occurred.'),避免向客户端泄露内部细节; - 响应体仅包含
name、message、code,以及HttpException的status字段。
调试模式(YII_DEBUG 为 true)下,响应体会额外附加:
type:异常类全名;file/line:异常抛出位置;stack-trace:堆栈跟踪数组;error-info:对于yii\db\Exception的数据库错误信息;previous:前序异常链(递归序列化)。
因此,在开发联调阶段你可以在响应体中直接看到完整堆栈,而生产环境则应依赖日志系统(logException 写入的分类)排查问题,保持 API 响应简洁安全。
七、实战要点小结
- 首选内置异常类:REST 场景下抛异常时,优先使用第二节表格中的内置异常类,语义清晰、状态码固化,无需手动维护映射;
- 消息面向客户端:
HttpException继承自UserException,其message会原样展示给客户端,请勿在其中暴露敏感信息(数据库细节、堆栈路径等);内部错误应抛出普通异常,由框架在生产模式自动替换为通用 500 消息; - 自定义格式用 beforeSend:第四节的事件方案同时作用于成功与失败响应,且发生在序列化之前,是官方推荐的统一改造入口;如需全局(不依赖
suppress_response_code参数)改造,去掉条件判断即可; - 状态码语义要严格遵守:第三节的速查表是 Yii REST 框架与客户端约定俗成的契约,例如
422专用于校验失败、429专用于限流拒绝,滥用状态码会破坏客户端(含自动生成 SDK)的解析逻辑; - 限流集成:
429对应的TooManyRequestsHttpException由 REST 限流过滤器在超限时自动抛出,详见 docs/guide-ru/rest-rate-limiting.md。
八、延伸阅读
- 官方英文版错误处理指南:docs/guide/rest-error-handling.md
- REST 请求处理总览:docs/guide-ru/rest-quick-start.md
- REST 控制器与动作:docs/guide-ru/rest-controllers.md
- 通用错误处理与日志:docs/guide-ru/runtime-handling-errors.md
- 响应格式化(JSON/XML 输出细节):docs/guide-ru/rest-response-formatting.md