如何调试 API 请求：开发者实用指南

API 以可预测的方式失败

当 API 调用失败时，大多数开发者会立即打开网络标签或添加 console.log 语句。这虽然有效，但有一种更快的思维模型：每个 API 失败都属于五类之一，而 HTTP 状态码会告诉你属于哪一类。一旦知道类别，修复方法通常就很明显了。

第一步：读取状态码

状态码是最重要的诊断信号。切勿跳过。

4xx — 你发送的内容有误

5xx — 服务器出错了

5xx 几乎从来不是你的错。在调试自己的代码之前，先检查服务状态页面。

第二步：检查 URL

比开发者预期的更多的 API bug 可追溯到格式错误的 URL。请系统地检查以下内容：

协议 — http 与 https。许多 API 拒绝纯 HTTP 连接或静默重定向。

主机 — 一个拼写错误就会让你连接到错误的服务器或根本连不上。

路径 — 注意缺少前导斜杠、双斜杠或错误的版本前缀（v1 vs v2）。

查询参数 — 值必须进行 URL 编码。空格必须变成 %20；值中的 & 必须变成 %26。在 JavaScript 中动态构建 URL 时，始终使用 encodeURIComponent()。

// 错误——如果 name 包含 &、= 或空格则会出错
const url = `https://api.example.com/search?name=${name}`;

// 正确
const url = `https://api.example.com/search?name=${encodeURIComponent(name)}`;

第三步：检查认证

401 和 403 的区别很重要：

• 401 — 服务器不知道你是谁。凭据缺失、过期或格式错误。
• 403 — 服务器知道你是谁，但不允许该操作。这是权限问题。

对于 JWT Bearer 令牌，解码令牌并检查 exp 声明（过期时间，Unix 时间戳）、aud 声明（目标受众）以及任何 scope 或 permissions 声明。你不需要签名密钥即可读取声明——只有验证签名时才需要。

对于 API 密钥，请确认密钥位于正确的请求头中，并确认你正在为正确的环境使用密钥。生产环境的密钥通常无法在测试端点使用。

对于 Basic Auth，请求头值是 base64(username:password)。解码它以确认凭据正确。

第四步：验证请求体

400 和 422 错误通常意味着请求体有问题。仔细阅读错误响应——它通常会指明哪个字段失败。

常见的请求体问题：

错误的 Content-Type — 发送 JSON 时如果没有 Content-Type: application/json 请求头，某些服务器会完全忽略请求体。

尾随逗号 — 在 JavaScript 中有效，但在 JSON 中无效。值 {"key": "value",} 会导致大多数服务器 JSON 解析失败。

类型错误 — 发送字符串 "123" 而需要整数 123，或发送 "true" 而需要布尔值 true。

null 与缺失 — 某些 API 将显式的 null 与省略的字段区别对待。

第五步：诊断 CORS 错误

CORS 错误仅发生在浏览器中。相同的请求可能从 curl 或 Postman 成功，但在你的 Web 应用中失败，因为浏览器强制执行同源策略，并要求服务器明确允许跨域请求。

CORS 问题的迹象：浏览器控制台显示“Access to fetch has been blocked by CORS policy”，网络标签显示状态码为 0，并且该请求从 Postman 可以正常工作。

修复必须在服务器端进行。无法从浏览器禁用 CORS。检查服务器是否将 Access-Control-Allow-Origin 设置为你的源或 *，以及它是否处理需要 Authorization 请求头的路由的预检 OPTIONS 请求。

第六步：使用 curl 隔离问题

使用 curl 消除所有客户端变量。如果请求在 curl 中有效但在你的代码中无效，则 bug 在你的代码中。如果在 curl 中有效但在浏览器中无效，则是 CORS 问题。

# 带认证头的 GET 请求
curl -v -H "Authorization: Bearer your_token" https://api.example.com/users

# 带 JSON 请求体的 POST 请求
curl -v -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token" \
  -d '{"name":"test","email":"test@example.com"}' \
  https://api.example.com/users

-v 标志显示完整的请求和响应头。调试时始终包含它——大多数 bug 隐藏在请求头中。

调试工具集

→ 从 URL 解析器 开始，分解任何端点 URL，立即捕获编码或路径错误。