用 curl 快速排查接口问题：从状态码到响应体一次定位

接口调不通时，别先怀疑代码。curl 一条命令就能看到状态码、响应头和响应体，大多数接口问题在这一层就能定性：是网络不通、鉴权失败，还是服务端报错。

一、先看状态码，别直接看业务报错

curl -i https://api.example.com/health
curl -o /dev/null -s -w "%{http_code} %{time_total}s\n" https://api.example.com/users

-i 同时打印响应头和响应体，-w 只输出状态码和耗时。先分清楚是哪一类问题：000 是根本没连上（DNS、网络、端口），401/403 是鉴权问题，404 是路径错了，500 系列才是服务端内部错误。状态码定性错了，后面全白忙。

二、超时和连接失败：分开看三个阶段

curl -v https://api.example.com/users --max-time 10

-v 会打印 DNS 解析、TCP 连接、TLS 握手三个阶段。卡在 DNS 就是域名问题，卡在 TCP 就是端口或防火墙问题，卡在 TLS 就是证书问题。三个阶段一分，排查范围立刻收窄到一处。

接口偶尔慢、偶尔正常时，用多次请求看耗时分布：

for i in 1 2 3 4 5; do curl -o /dev/null -s -w "%{time_total}\n" https://api.example.com/users; done

耗时忽高忽低多半是服务端负载或网络抖动，稳定超时则多半是下游依赖挂了。

三、POST 调试：把请求体和请求头一次发对

curl -X POST https://api.example.com/login \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"test123"}'

接口文档说要 JSON 就别发表单，Content-Type 错了服务端直接 400 或 415。调试时把 -d 的内容先写进文件再用 --data @body.json 发，避免 shell 转义把引号吃掉：

curl -X POST https://api.example.com/login \
  -H "Content-Type: application/json" \
  --data @body.json

需要带 Token 时用 -H "Authorization: Bearer <token>"，先确认 Token 没过期再怀疑接口逻辑——过期 Token 导致的 401 是最常见的“接口坏了”。

四、响应体看不懂：先格式化再读

curl -s https://api.example.com/users | python3 -m json.tool | head -n 50

JSON 挤在一行里没法读，管道给 json.tool 格式化后再看。先看顶层字段有没有 error、code、message，再往下翻业务数据。很多“返回不对”其实是字段名或分页参数理解错了，格式化后一眼就能看出来。

小结

接口排查的固定顺序：状态码定性 → -v 看连接阶段 → POST 核对请求头和请求体 → 响应体格式化再读。curl 不用装、不用配，定位先于改代码，别一上来就改实现去撞运气。