curl 排查接口问题实战：从状态码、耗时到请求头的一套组合拳

接口"偶尔很慢""偶尔 502"，浏览器和 Postman 都不好复现。在服务器上，一个 curl 加几个参数，就能把问题定位到 DNS、建连、TLS、服务端处理还是传输的哪一段。

一、先看最基本的：状态码和响应头

curl -sS -o /dev/null -D - https://example.com/api/health

-s 静默，-S 保留错误信息，-o /dev/null 丢弃响应体，-D - 把响应头打到标准输出。先确认状态码、Content-Type、Location（有没有被重定向）以及 Server、Via 这类能看出经过了哪层网关的头。

只想要状态码：

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

二、用 -w 拆解耗时

这是最有用的技巧。把下面的格式存成 curl-format.txt：

dns:        %{time_namelookup}s
connect:    %{time_connect}s
tls:        %{time_appconnect}s
ttfb:       %{time_starttransfer}s
total:      %{time_total}s
size:       %{size_download} bytes

然后执行：

curl -s -o /dev/null -w @curl-format.txt https://example.com/api/list

读法是看相邻两项的差值：

• dns 偏大：解析慢，检查 /etc/resolv.conf 和上游 DNS。
• connect - dns 偏大：网络链路或安全组、防火墙问题。
• tls - connect 偏大：握手慢，可能是证书链过长或 CPU 紧张。
• ttfb - tls 偏大：请求已发出，服务端处理慢，应去看应用日志和数据库。
• total - ttfb 偏大：响应体大或带宽不足，考虑开压缩。

三、带请求头、带数据地调用

curl -sS -X POST https://example.com/api/orders \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer $TOKEN' \
  -d '{"sku":"A1001","qty":2}'

注意单引号里的 $TOKEN 不会被展开，需要展开时改用双引号，或者先 export 再用 "Authorization: Bearer $TOKEN"。数据较大时用 -d @body.json 从文件读取。

四、看清握手和协商过程：-v

curl -v https://example.com/ 2>&1 | head -40

* 开头的行是连接和 TLS 信息，> 是发出的请求，< 是收到的响应。证书不匹配、协议协商到 HTTP/1.1 还是 HTTP/2、有没有走代理，在这里一目了然。

五、绕过 DNS，直接指定后端

灰度或多台机器时，想确认是哪一台有问题：

curl -sS --resolve example.com:443:10.0.0.12 https://example.com/api/health -o /dev/null -w '%{http_code}\n'

--resolve 让域名固定解析到指定 IP，同时保留 SNI 和 Host，所以证书校验和虚拟主机匹配都和线上一致。对每个后端 IP 循环一遍，就能找出那台"坏节点"。

六、超时与重试，别让脚本卡死

curl -sS --connect-timeout 3 --max-time 10 --retry 2 --retry-delay 1 https://example.com/api/health

--connect-timeout 限制建连，--max-time 限制整个请求。巡检脚本一定要同时设置，否则一个挂住的连接会拖死整个任务。

七、复现"偶尔慢"：循环采样

for i in $(seq 1 20); do
  curl -s -o /dev/null -w '%{http_code} %{time_total}\n' https://example.com/api/list
  sleep 1
done

把输出再用 sort -k2 -n | tail -3 看最慢的几次，对照服务端同一时间段的日志，往往能发现是某个定时任务或慢查询造成的抖动。

小结

排查接口的顺序可以固定下来：先看状态码和响应头，再用 -w 拆解耗时，接着用 -v 看握手细节，最后用 --resolve 逐台验证后端。每一步都有明确的数字，不必靠猜。