Yii 2 REST API 错误处理完整指南:异常驱动的 HTTP 错误响应与自定义格式

原创2026-09-22 12:41:241,344 阅读
文章标签:后端Web框架

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):

  1. 注册:应用启动时,ErrorHandler::register()(framework/base/ErrorHandler.php)调用 set_exception_handler() 与 set_error_handler(),将未捕获异常与 PHP 错误统一接管;
  2. 捕获:未捕获异常进入 handleException()(framework/base/ErrorHandler.php),记录异常并清空已输出内容;
  3. 日志:logException() 以 yii\web\HttpException:404 这样的分类写入日志(framework/base/ErrorHandler.php),方便按状态码检索错误;
  4. 渲染:renderException()(framework/web/ErrorHandler.php)重置 response 对象 → 通过 setStatusCodeByException() 设置状态码 → 按格式输出:
    • HTML 格式:渲染错误视图(errorView/exceptionView);
    • RAW 格式:输出纯文本异常;
    • 其他格式(JSON/XML 等 REST 场景):调用 convertExceptionToArray() 序列化异常为数组;
  5. 发送: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 响应简洁安全。

七、实战要点小结

  1. 首选内置异常类:REST 场景下抛异常时,优先使用第二节表格中的内置异常类,语义清晰、状态码固化,无需手动维护映射;
  2. 消息面向客户端:HttpException 继承自 UserException,其 message 会原样展示给客户端,请勿在其中暴露敏感信息(数据库细节、堆栈路径等);内部错误应抛出普通异常,由框架在生产模式自动替换为通用 500 消息;
  3. 自定义格式用 beforeSend:第四节的事件方案同时作用于成功与失败响应,且发生在序列化之前,是官方推荐的统一改造入口;如需全局(不依赖 suppress_response_code 参数)改造,去掉条件判断即可;
  4. 状态码语义要严格遵守:第三节的速查表是 Yii REST 框架与客户端约定俗成的契约,例如 422 专用于校验失败、429 专用于限流拒绝,滥用状态码会破坏客户端(含自动生成 SDK)的解析逻辑;
  5. 限流集成:429 对应的 TooManyRequestsHttpException 由 REST 限流过滤器在超限时自动抛出,详见 docs/guide-ru/rest-rate-limiting.md。

八、延伸阅读

登录后查看全文
yii2