API 响应 JSON 调试清单

这个页面解决什么问题

API 响应异常并不总是 JSON 语法问题。200 状态码可能携带业务错误，401/403 可能返回登录页，网关 502 可能返回 HTML，日志系统还可能把 traceId、时间戳和服务名前缀包在 JSON 外面。本页把响应排查拆成网络、头部、正文、结构和字段五层。

这类清单适合接口联调、Webhook 排查、前后端字段对齐、SDK 报错复现和监控告警归因。目标不是把任意文本都格式化成功，而是确认“我拿到的到底是不是预期 JSON 响应”。

快速判断

• 状态码不是 2xx 时，不要先改 JSON，先看认证、路径、网关和上游服务。
• Content-Type 不是 application/json 时，确认是否返回 HTML、纯文本、文件或压缩内容。
• 响应体开头不是 { 或 [，应先判断外壳来源。
• 格式化后字段类型与接口文档不同，例如数字 ID 变成字符串，才进入业务层排查。

可复制示例：错误输入与修复后输入

下面的坏样例来自日志，不是纯响应体；修复样例只保留 payload 中的 JSON。

2026-06-01T09:00:00Z INFO trace=abc payload={"code":0,"data":{"id":"1001"}}

{"code":0,"data":{"id":"1001"}}

如果把整行日志放进 JSON 解析器，错误会出现在开头的时间戳。正确做法是只提取响应体，保留 traceId 在排查记录中，而不是混进 JSON 样本。

诊断步骤

1. 记录请求方法、URL、环境、状态码和 Content-Type。
2. 确认响应体是原始 body，而不是浏览器对象预览或日志包装。
3. 把响应体脱敏并缩小到能复现问题的最小 JSON。
4. 使用 JSON 格式化工具 查看顶层字段、错误对象和 data 结构。
5. 对照接口文档检查必填字段、nullable 字段、数组长度和字段类型。
6. 把最终结论写成“网络层/认证层/格式层/业务层”之一。

API 响应排查要避免层级跳跃。一个 HTML 登录页不应被当成 JSON 错误，一个业务 code 失败也不应被当成 HTTP 成功。分层记录能降低重复沟通成本。

常见错误表

常见误判

• 把 curl 输出、响应头和正文一起复制进 JSON 工具。
• 只看 status code，不看业务 code 和 message。
• 把后端日志中的 payload 字符串当成已经解析好的对象。
• 只保存格式化后的结果，不保存原始响应来源。

清单的价值在于固定排查顺序。对外反馈时，建议附上状态码、Content-Type、脱敏响应体和已确认的字段层级。

隐私、安全和适用边界

用于排查时请使用脱敏样本。不要粘贴访问令牌、Cookie、客户资料、内部域名、未公开商业规则、支付记录或完整生产日志。页面适合处理公开示例、教学片段、复现样本和已经替换真实值的配置。

本页不能判断接口权限是否正确，也不能替代服务端日志、契约测试、监控平台或第三方 API 官方控制台。它只帮助整理可读响应和确认 JSON 结构。

复制或发布前复核清单

1. 是否记录了请求方法、URL、状态码和 Content-Type。
2. 是否只复制响应体，没有混入响应头或日志外壳。
3. 是否确认响应体是严格 JSON。
4. 是否检查顶层 code、message、data、error 等字段。
5. 是否用脱敏样本保存排查记录。
6. 是否回到目标环境验证修复结论。

相关工具和延伸阅读

参考依据

• HTTP Content-Type 与状态码应以接口实际响应为准。
• MDN JSON.parse()：解析前必须是严格 JSON 文本。
• Ymir Tool URL 编码工具：用于排查查询参数被错误编码的问题。

编辑记录：Ymir Tool editorial review，2026-06-01。本页作为 Sprint 3 新增案例/排错内容发布，目标是把单一工具入口扩展为可复核的任务说明、错误示例和操作边界。