Yii框架REST状态码返回方法

Yii框架中REST接口的状态码绝非靠手动调用setStatusCode()硬设，而应严格遵循REST语义，通过抛出对应HttpException（如NotFoundHttpException、UnauthorizedHttpException等）由框架自动处理——这不仅避免响应头已发送导致状态码失效的常见陷阱，还能确保ContentNegotiator、错误处理器和控制器行为协同输出一致、规范的JSON或HTML响应；尤其要注意DELETE操作资源不存在时应返回204而非404，与GET形成语义区分，否则将误导前端重试逻辑和监控系统。

Yii RESTful 接口的状态码不是靠手动调用 setStatusCode() 写出来的，而是由控制器行为、异常类型和错误处理器共同决定的——硬设容易被覆盖，且违背 REST 语义。

为什么 response->setStatusCode(404) 在 REST 控制器里经常失效

yii\rest\Controller 默认启用 ContentNegotiator 和 HttpException 自动处理机制，一旦你调用 render()、asJson() 或输出任何内容（包括空格、BOM、调试 var_dump），响应头就已发送，再改状态码无效。

• 常见错误现象：在 actionView() 末尾写 Yii::$app->response->setStatusCode(404)，但 curl 看到仍是 200
• 根本原因：REST 控制器的 beforeAction() 已注册了 authenticator、rateLimiter 等行为，它们可能提前抛出异常或触发输出
• 更隐蔽的坑：调试工具条（debug toolbar）、日志组件（如 FileTarget 的 export()）在响应结束前 flush 输出缓冲，也会锁死状态码

REST 接口中正确返回 404、401、403 等状态码的方式

不要手动设码，而是抛出对应异常——这是 Yii 的约定，也是 REST 的语义表达。

• throw new \yii\web\NotFoundHttpException('Resource not found'); → 自动返回 404 + JSON（API 场景）或 HTML（Web 场景）
• throw new \yii\web\UnauthorizedHttpException('Token expired'); → 返回 401
• throw new \yii\web\ForbiddenHttpException('Insufficient permissions'); → 返回 403
• 在 yii\rest\ActiveController 子类中，findModel() 方法内部查不到记录时，直接 throw 即可，不用 if-else 包裹 setStatusCode()

自定义错误响应结构（比如统一加 code 字段）的关键位置

真正起作用的地方不是控制器，而是 errorHandler 组件的 errorAction 视图或 action 逻辑。

• 确保 config/web.php 中启用了 errorHandler：'errorHandler' => ['errorAction' => 'site/error']
• 在 SiteController::actionError() 里判断请求类型：if (Yii::$app->request->getIsAjax() || Yii::$app->request->getIsJsonp())，然后 return $this->asJson(['code' => 404, 'message' => $exception->getMessage()])
• 绝对不要在 actionError 里再 throw 新异常，否则会触发递归崩溃
• 若使用 yii\rest\Controller，它默认把 NotFoundHttpException 映射为 name: "Not Found" + message + status: 404，无需额外配置

POST/PUT/DELETE 成功后该返回什么状态码

REST 不是所有成功都返回 200。状态码要匹配操作意图：

• POST 创建资源成功 → 必须用 201 Created，并带 Location 头指向新资源 URI（yii\rest\ActiveController 默认已实现）
• PUT/PATCH 更新成功 → 推荐 200 OK（返回更新后完整资源）或 204 No Content（不返回 body，适合轻量更新）
• DELETE 成功 → 推荐 204 No Content；如果删除目标本就不存在，也应返回 204（而非 404），因为“删除一个不存在的东西”在语义上是成功的空操作
• 注意：Yii 默认对 ActiveController::actionDelete() 返回 200，需重写该 action 手动设 Yii::$app->response->setStatusCode(204) 并 return null

最容易被忽略的是 DELETE 和 GET 对“资源不存在”的语义差异：GET 找不到是 404，DELETE 找不到却是 204——这个边界不厘清，前端重试逻辑和监控告警都会误判。

今天关于《Yii框架REST状态码返回方法》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于Yii框架的内容请关注golang学习网公众号！