yii restful接口返回json需控制器、内容协商、序列化器、解析器四者协同，缺一不可；必须继承yii\rest\controller或其子类，配置contentnegotiator和request.parsers，并确保模型实现fields()。
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 的实际值，比翻文档更快。
