Yii框架JSON返回与数据格式化教程

本文深入解析了Yii框架构建RESTful JSON接口的核心机制，强调JSON响应并非简单调用json_encode或临时设置response格式，而是依赖控制器继承、内容协商、序列化器与请求解析器四者严密协同的完整流程；文章直击开发者常见误区——如误用yii\web\Controller、忽略Accept头导致返回HTML错误页、未配置JsonParser致使POST JSON数据无法解析等，并给出精准配置示例和调试建议，帮助读者避开500错误、空响应、Content-Type错乱及参数丢失等典型陷阱，真正掌握Yii RESTful接口稳定输出JSON的底层逻辑与最佳实践。

Yii RESTful 接口返回 JSON 不是靠“手动 echo json_encode()”或者临时改 response->format，而是靠整个请求响应链的协同：控制器类型、内容协商机制、序列化器、解析器四者缺一不可。错一个环节，就会出现 500、空响应、Content-Type 是 text/html、或 POST JSON body 拿不到参数。

必须继承 yii\rest\Controller 或其子类

用 yii\web\Controller 写 REST 接口，哪怕里面写了 Yii::$app->response->format = \yii\web\Response::FORMAT_JSON，也大概率失败——因为没走 Yii2 的 REST 响应流程，Serializer 不介入，状态码不自动映射，错误也不 JSON 化。

• 正确写法：class UserController extends yii\rest\ActiveController { public $modelClass = 'app\models\User'; }
• 如果要自定义逻辑，继承 yii\rest\Controller，动作方法直接 return 数组或模型实例，不要 echo / print_r / exit
• 返回模型时，确保它实现了 fields()；否则访问私有属性会抛 InvalidParamException
• 返回 ActiveQuery（比如 User::find()）会报 "Calling unknown method: yii\db\ActiveQuery::toArray()" —— 必须先 ->all() 或 ->one()

Content-Type 和 Accept 头决定是否走 JSON 流程

Yii2 默认按请求头里的 Accept 字段做内容协商（content negotiation），不是“所有请求都吐 JSON”。发个 curl 不带 -H "Accept: application/json"，哪怕后端配置了 JSON 格式，也可能返回 HTML 错误页或 406 Not Acceptable。

• 测试时务必带上：curl -H "Accept: application/json" http://localhost/users
• 若想强制所有请求都走 JSON（比如内部系统），在控制器里加 behavior：'contentNegotiator' => ['class' => \yii\filters\ContentNegotiator::class, 'formats' => ['application/json' => \yii\web\Response::FORMAT_JSON]]
• 注意：'text/html' => \yii\web\Response::FORMAT_JSON 这种写法虽能覆盖浏览器直连，但会破坏标准协商逻辑，调试时容易混淆

POST/PUT 的 JSON body 要能被解析，得配 request->parsers

默认情况下，Yii2 只从 $_POST 和 query string 解析参数。{"name":"test"} 放在 request body 里，$request->post('name') 一定为空——这不是 bug，是设计如此。

• 必须在 config/web.php 的 components['request'] 中声明：'parsers' => ['application/json' => 'yii\web\JsonParser']
• 支持的 MIME 类型要写全：'application/json'、'text/json' 都建议加上
• 配完之后，$request->bodyParams 才会有解析后的数组；$request->post() 仍为空，别混用
• 如果收到 Invalid JSON data in request body: control character error，通常是前端发了不可见控制字符（比如富文本粘贴进来的零宽空格），可临时加 Yii::info($request->getRawBody(), __METHOD__) 查看原始体

绕过自动序列化时，return 比 echo 安全得多

某些场景（如 Webhook 回调、导出接口、返回自定义结构）确实需要跳过 Serializer。这时不能 echo json_encode(...)，否则 Response 的状态码、Header、事件钩子全失效。

• 正确方式：Yii::$app->response->format = \yii\web\Response::FORMAT_RAW; Yii::$app->response->headers->set('Content-Type', 'application/json'); return json_encode([...]);
• 更稳妥的封装是单独写个行为（Behavior）或 ResponseFormatter，避免每个 action 都重复设 header
• 注意：这种写法下，异常也不会自动 JSON 化，需自己 catch 并构造 error 响应

最容易被忽略的是 Accept 头和 request->parsers 的联动——它们不在同一个配置块里，但共同决定一次请求能不能进对的管道。调不通时，先抓包看请求头，再查日志里 bodyParams 和 response->data 的实际值，比翻文档更快。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~