Yii框架错误修复技巧分享

本文深入解析了 Yii 框架在构建 API 服务时面临的核心痛点——默认 HTML 异常渲染导致客户端无法解析错误响应，并提供了一套完整、健壮且生产可用的 JSON 错误格式化修复方案：通过精准拦截请求类型、重写 errorHandler 组件与 errorAction、统一异常响应结构（{code, message, data}）、建立 HTTP 状态码到业务 code 的映射表，以及关键的执行约束（如禁止二次抛出、确保返回数组、兜底状态码处理等），彻底绕过 Yii 默认的 HTML 渲染链，让所有异常——无论来自控制器、过滤器、模型验证还是数据库层——都经由同一套纯 JSON 响应管道输出，从而保障 API 错误的一致性、可读性与前端友好性。

Yii 框架默认把所有异常渲染成 HTML 页面，API 请求拿到的要么是空响应、要么是混着 标签的 JSON，根本没法被客户端正常解析。必须绕过 yii\web\ErrorHandler 的 HTML 渲染链，让所有错误走纯 JSON 流程。

怎么禁用 ErrorHandler 的 HTML 渲染？

别指望靠 'responseFormat' => \yii\web\Response::FORMAT_JSON 全局配置——它只管正常返回，不管异常。关键动作是切断 yii\web\ErrorHandler 对 API 请求的接管：

• 在 config/web.php 的 components 里移除或重写 'errorHandler' => ['errorAction' => 'site/error']
• 更稳妥的做法：在应用启动早期（比如 bootstrap 或 beforeAction）判断请求类型：Yii::$app->request->getIsJson() || Yii::$app->request->getIsAjax()
• 满足条件时，直接 throw new \yii\web\HttpException(400, 'Bad Request')，让自定义响应处理器捕获，而不是交给默认 handler 渲染 HTML

如何让 actionError 返回标准 {“code”, “message”, “data”}？

核心不是改 view，而是替换 renderException() 行为。最轻量方式是在 components 中注册自定义 error handler：

'errorHandler' => [
    'class' => 'yii\web\ErrorHandler',
    'errorAction' => 'api/error',
],

然后在 controllers/ApiController.php 实现 actionError()：

public function actionError()
{
    $exception = Yii::$app->errorHandler->exception;
    if ($exception !== null) {
        Yii::$app->response->statusCode = $exception->statusCode ?: 500;
        return [
            'code' => $exception->getCode() ?: 50000,
            'message' => $exception->getMessage(),
            'data' => [],
        ];
    }
}

• $exception->statusCode 只对 HttpException 子类有效，普通 Exception 是 null，必须兜底设为 500
• 这个 action 必须返回数组，Yii2 会自动 JSON 化；不能 echo 或 die
• 千万别在 actionError 里再 throw 异常，否则二次进入 error handler，可能死循环

400/401/403/404 状态码怎么映射到业务 code？

硬写 if ($exception instanceof \yii\web\BadRequestHttpException) 太脆弱。推荐用状态码查表映射：

$codeMap = [
    400 => 10001,
    401 => 10002,
    403 => 10003,
    404 => 10004,
    500 => 50000,
];
$code = $codeMap[$exception->statusCode] ?? 50000;

• 不要依赖 $exception->getCode() 做业务区分——它常是 0，且和 HTTP 状态码语义不一致
• 如果项目用了自定义异常类（如 ApiBadRequestException），可以在构造时显式传入业务 code，比查表更可控
• 注意：422（验证失败）这类状态码容易被忽略，要单独加进映射表，否则前端收不到明确提示

真正难的不是格式化，而是确保所有入口（控制器、过滤器、模型验证、数据库层抛出的异常）都经过同一套响应管道。漏掉一个 try/catch 或一个未注册的 filter，就可能冒出原始堆栈或 HTML 片段。

以上就是《Yii框架错误修复技巧分享》的详细内容，更多关于Yii框架的资料请关注golang学习网公众号！