API 调试实战手册：从抓包到合同校验

API 出问题时，先收集证据再猜原因

生产 API 故障很少只给一行清晰错误。可能是网关 502、200 却返回 {"success":false}、截断的 JSON、或「Postman 能过、App 不行」的 JWT。高效团队把调试当成可重复流水线：抓取请求 → 规范化响应 → 与已知良好版本 diff → 校验合同 → 再缩小到鉴权、路由或语义。

本 playbook 用 Towalles 浏览器本地工具走完该流程。操作不会把抓取内容上传到 Towalles 服务器——粘贴前仍须脱敏 Token 与客户字段。JSON 技巧见 json-formatting-guide；URL 边界见 url-api-debugging-guide。

阶段一：抓取并解析请求

最小复现 — 一个失败端点、一种身份、一种 payload。记录 method、path、query、headers（脱敏 Authorization）与 body。

解析 URL — 将完整 URL 贴入 url-parser，确认协议、主机、路径段与解码后的 query。双重编码（%252F）与 query 里 + / 空格差异会导致客户端 SDK 静默不一致。

编码排查 — 参数乱码时，用 url-encoder、base64-encoder-decoder 检查编码叠加（JSON 里的 URL 编码再 Base64）。

在事故文档记录：「query filter 解码为空，因客户端发送了无值的 filter=。」

阶段二：规范化响应体

先格式化 — 压缩的错误 JSON 把真因藏在 error.details[0].message 深处。贴入 json-formatter。若解析失败，可能是 HTML 错误页、SSE 分片或截断 gzip——对照 Network 的 Content-Type 与 body 长度。

从 LLM 包装中提取 — AI 网关常返回 Markdown 代码块。正文混杂 prose 与 JSON 时，先用 llm-json-extractor 再格式化。

跨环境对比 — 保存 staging 与 production 响应（脱敏），分别格式化后用 json-diff 看路径级差异。常见发现：缺少 data.version、类型从 number 变 string，导致移动端严格解析失败。

示例：

// staging
{ "user": { "id": 42, "tier": "pro" } }
// production
{ "user": { "id": "42", "tier": "pro" } }

仅格式化看不出 ID 类型变化；diff 可以。

阶段三：鉴权与 Token

401/403 或间歇失败时：

1. Bearer Token 贴入 jwt-decoder（自动去掉 Bearer ）。
2. 查 exp、nbf、aud、iss 与时钟偏差。
3. 核对自定义声明（scope、roles）与路由策略。
4. 牢记：解码不是验签——结合服务端日志查签名失败。

不透明 API Key 用 api-key-format-checker 识别厂商格式，确认未混用 test/live 前缀。若 live key 出现在工单附件，立即轮换。

hmac-generator 仅用于本地测试向量复现——勿粘贴生产签名密钥。

阶段四：合同与 Schema

语法合法的 JSON 仍可能违反 OpenAPI。格式化后：

• 用 structured-output-validator 对照 JSON Schema fixture。
• 用 openapi-formatter 查组件定义，确认字段在 spec 中存在。

CI 应长期做 schema 校验；事故中手动跑 validator 可区分「服务端漂移」与「客户端假设错误」。

配置驱动 API 时，用 yaml-converter 转换部署 YAML，格式化后与上一版 json-diff（思路同 yaml-toml-config-guide）。

阶段五：时间、Cron 与幂等

定时任务失败？用 cron-validator 校验表达式（参见 cron-scheduling-guide）。差一小时时区会让批量窗口错位，看起来像「随机」API 故障。

重试风暴时检查幂等键（常为 UUID）——用 uuid-generator / ulid-generator 生成测试 ID，并在 API 目录记录期望 header 名。

阶段六：沟通与收尾

事故评论模板

• 请求：method、path、query 摘要（无密钥）
• 响应：status、错误路径格式化摘录
• Diff：相对上次良好版的变化
• 鉴权：exp/aud/iss 摘要（无 raw token）
• 下一负责人：后端 / 网关 / 客户端

事后 — CI 增加 fixture、runbook 链到 json-formatting-guide、轮换已暴露凭证。

工具链速查

浪费时间的坑

• 在共享标签用 live refresh token 调试生产。
• 以为「能格式化」就等于服务端发了合法 JSON（代理可能改写 body）。
• 忽略 Content-Encoding 与双重解析字符串。
• 不做 diff——肉眼扫 200 行对象找一处字段变更。

Towalles 工具页会链到专题指南；本 playbook 把它们串成事故可用顺序。下次 SEV-2 前收藏 api-debugging-playbook，按阶段执行再谈「是不是缓存问题」。

附录：完整示例（合成数据）

现象 — 网关发布后移动端登录失败；Postman 同 bearer 返回 200。

阶段一 — url-parser 解析 https://api.example.com/v2/users/me?fields=profile,settings，确认路径 /v2/users/me（网关新增 /v2 剥离规则）。

阶段二 — json-formatter 格式化移动端错误体：

{"error":{"code":"PROFILE_SHAPE","details":[{"path":"user.id","expected":"number"}]}}

阶段三 — jwt-decoder：exp 有效；aud 为 mobile-app；非鉴权问题。

阶段四 — json-diff 对比 staging/production 的 user → production id 在序列化变更后变为 string。

解决 — 后端 hotfix 强制 number；用 structured-output-validator 加 schema 测试；runbook 链到 api-debugging-playbook。

按序用工具相对随机 grep 日志，跨团队事故通常可省 30–90 分钟。

附录：状态码路由表

附录：curl → Towalles 交接

curl -sS -D - https://api.example.com/health -o /tmp/body.json

将 /tmp/body.json 复制到 json-formatter；响应头写入事故文档（脱敏 cookie）。勿把 live token 写进 shell history——用事后清除的环境变量。

curl 负责传输、Towalles 负责检视，符合 choosing-local-online-tools 的混合模式。