Yii框架设置JSON和XML返回格式方法

本文深入解析了 Yii 框架中 JSON 和 XML 响应格式的精准控制方法，强调必须显式设置 `response->format` 而非依赖请求头自动协商，详解了避免中文乱码、循环引用导致空响应、XML 格式器手动注册与 ContentNegotiator 正确配置等关键实践，并指出常见失效陷阱（如缺失 MIME 类型注册、前端未发送 Accept 头），同时提供 API 异常统一 JSON 化的可靠方案——每一步都直击生产环境中的真实痛点，帮你避开“看似配置正确却返回 HTML 或 406”的隐形坑。

Yii 框架默认不自动按请求头返回 JSON 或 XML，必须显式设置 response->format，否则即使客户端发 Accept: application/json，也可能返回 HTML 或 406 错误。

怎么让 action 返回 JSON 数据

最稳的方式是在每个需要 JSON 的 action 开头写：

\Yii::$app->response->format = \yii\web\Response::FORMAT_JSON;

之后直接 return 数组、ActiveRecord 对象或对象数组即可。注意以下几点：

• 必须在 return 前执行，不能放在 beforeAction 或行为里全局设——容易漏切回 HTML
• 默认 JsonResponseFormatter 不启用 JSON_UNESCAPED_UNICODE，中文会变成 \u4f60；需在 config/web.php 的 response.formatters 中补上：'encodeOptions' => JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
• 如果返回值含 DateTime、resource 或循环引用，json_encode() 会静默失败，响应体为空但状态码仍是 200；建议用 try/catch 包裹或提前转换

怎么让 action 返回 XML 数据

XML 支持不是开箱即用的，必须手动注册 XmlResponseFormatter 并确保 ContentNegotiator 行为生效，否则 Accept: application/xml 会 fallback 到 JSON 或直接 406。

两步缺一不可：

• 在 config/web.php 的 components.response.formatters 中添加：\yii\web\Response::FORMAT_XML => ['class' => 'yii\web\XmlResponseFormatter']
• 在控制器中启用 ContentNegotiator 行为（或手动设 format）：

  public function behaviors()
  {
      $behaviors = parent::behaviors();
      $behaviors['contentNegotiator'] = [
          'class' => 'yii\filters\ContentNegotiator',
          'formats' => [
              'application/json' => \yii\web\Response::FORMAT_JSON,
              'application/xml' => \yii\web\Response::FORMAT_XML,
          ],
      ];
      return $behaviors;
  }

• 返回值只能是数组或实现 Arrayable 接口的对象；字符串、HTML 片段、已渲染内容会直接报错

为什么 ContentNegotiator 行为有时不生效

常见失效场景不是配置错了，而是请求本身没带有效协商头或格式器未注册：

• 前端用 fetch 或 axios 默认不发 Accept 头，ContentNegotiator 就找不到匹配项，fallback 到默认格式（通常是 HTML）
• 没在 response.formatters 里注册 FORMAT_XML 对应的 XmlResponseFormatter，即使行为里写了 'application/xml' => FORMAT_XML，框架也找不到处理类，最终返回 406
• ContentNegotiator 的 formats key 必须是标准 MIME 类型（如 application/json），写成 json 或 text/plain 无效

怎么统一处理 API 异常响应为 JSON

抛异常时不要用原生 Exception，否则会进 500 页面；要让错误也走 JSON 输出，得配合 errorHandler 配置：

• 抛客户端错误用 throw new \yii\web\BadRequestHttpException('xxx')，业务异常继承 \yii\base\UserException
• 在 config/web.php 中配 'errorHandler' => ['errorAction' => 'site/error']
• SiteController::actionError() 里第一行必须设 \Yii::$app->response->format = \yii\web\Response::FORMAT_JSON，再 return 错误数组
• 别依赖 as json 行为来处理异常——它只管正常 action 返回，不接管异常流程

XML 格式器对嵌套结构敏感，比如数组键含特殊字符、空值层级过深，都可能生成无效 XML；JSON 虽然宽松，但编码和类型容错仍是手动控制点，不能全指望框架兜底。

到这里，我们也就讲完了《Yii框架设置JSON和XML返回格式方法》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于Yii框架的知识点！