API 调试流程：从失败请求到可验证的修复
先记录浏览器实际发送了什么，再区分请求格式、浏览器策略与服务端鉴权。每一步都给出要看的证据与修复后的验收条件。
先保存一份失败请求
在开发者工具 Network 中记录时间、完整 URL、方法、请求头、请求体、状态码和响应体。保留 OPTIONS 与实际请求两条记录，以及网关请求 ID。分享前把 Cookie、Authorization 和个人数据替换成测试值；下面的 example.com 地址只作示意。
POST https://api.example.com/orders
Origin: https://app.example.com
Content-Type: application/json
quantity=2这份请求声称发送 JSON，但请求体是表单语法。若接口约定为 JSON，应改为 {"quantity":2}；若接口只接受表单，应按接口文档使用对应类型。服务器可能返回 400、415 或自己的业务错误，不能只凭状态码断定原因。
常见问题直达
1）先把请求形态定准
先对照实际请求与接口约定，再决定改动哪一个字段。
- 核对最终 URL、重定向和方法。接口依赖重复参数或顺序时应保留原样；带签名的网址先原样复现，不要先清理参数。
- 对照 Content-Type 与实际请求体。声明 JSON 不会把表单转成 JSON；浏览器使用 FormData 时，由浏览器生成 multipart boundary。
- 用测试值制作最小请求，并确认服务端收到预期字段。本地格式化成功不代表接口接受这些字段。
2）核对协议层契约
检查 Header、CORS、Cookie 在网关和应用层是否一致。
- 出现 OPTIONS 时，对照 Access-Control-Request-Method、Access-Control-Request-Headers 与预检响应，再确认实际请求是否发出。
- credentials: include 场景中，存在的预检和实际响应都需正确的明确来源与 Access-Control-Allow-Credentials: true。通配来源或仅有 OPTIONS 成功都不够。
- Cookie 缺失时查看浏览器排除原因，核对 Domain、Path、Secure、SameSite 与凭据模式。SameSite=None; Secure 不能覆盖第三方 Cookie 阻止策略；还要检查经过网关后的最终响应头。
3）检查鉴权与响应载荷
分别核对可读声明、有效签名与服务端权限判断。
- 用一次性 JWT 检查 iss、aud、exp、nbf，时间声明使用 Unix 秒。解码只读取声明；验签需使用可信密钥与预期算法，之后仍要执行服务端声明和权限规则。
- 返回 200 却无法解析 JSON 时，查看 Content-Type 和响应体开头。登录页面或代理错误可能返回 HTML，应修复响应链路，而不是反复格式化错误页面。
- 在测试环境对照有效请求与刻意错误的凭据，记录服务端错误码和请求 ID。能做 Base64 解码或签名有效，都不等于获得访问权限。
用同一个案例验收修复
每次只改一个变量，并在原来的浏览器来源重新执行测试。确认状态、响应类型、返回字段与浏览器可读性都符合接口约定；再用错误凭据或不允许的来源核对拒绝行为。curl 能检查 HTTP 响应，但不执行浏览器 CORS 策略。
POST、付款或写入请求可能已经执行，即使浏览器没有读到响应。复现时使用测试环境与测试数据；按接口的幂等约定重试，避免重复写入。最后记录根因、实际改动和仍未验证的条件。