用 curl 调试 HTTP 接口的常用姿势

接口联调出问题时，先不要急着改代码。用 curl 把请求原样发一遍，往往能最快定位是请求写错了，还是服务端返回异常，还是网络中间出了问题。下面是日常最常用的几组姿势。

一、先看一眼：状态码与响应头

最常用的是 -i，它会把响应头和响应体一起打印出来：

curl -i 接口地址

先看第一行的状态码，再看几个关键响应头。Content-Type 能解释返回的是 JSON 还是纯文本、字符集是否对得上；Location 说明是否发生了重定向；Set-Cookie 则关系到登录态是否真的写回来了。如果只看到状态码还不够，就用 -v 看完整过程：

curl -v 接口地址

-v 会输出域名解析、连接建立、TLS 握手、发出的请求头和收到的响应头。怀疑代理、证书、重定向或者请求头被改写时，它比只看响应体有用得多。日常使用可以再加 -sS，让正常输出安静一些，出错时仍然显示错误信息。

二、发出不同请求：方法、请求头与请求体

默认是 GET。需要 POST JSON 时，要同时讲清方法、请求头和请求体：

curl -X POST -H "Content-Type: application/json" -d '{"name":"test","count":1}' 接口地址

这里 -X 指定方法，-H 追加请求头，-d 发送请求体。常见坑有三个：一是忘了加 Content-Type，服务端按表单解析 JSON 就会报错；二是 JSON 引号写错，在 Shell 里通常用单引号包住整个 JSON，里面用双引号；三是把鉴权头漏了，导致明明参数正确却返回未授权。带鉴权头的写法是：

curl -H "Authorization: Bearer 你的令牌" 接口地址

GET 请求带查询参数时，可以用 -G 配合 --data-urlencode，让参数自动做编码，避免中文或特殊字符把地址拼坏。上传文件则用 -F，它会按表单方式组织请求体，和页面上传更接近。

三、只看关键结果：状态码与耗时

排查性能问题时，不需要每次都看完整响应体。用 -o 把响应体丢弃，再用 -w 只输出想要的指标：

curl -s -o /dev/null -w "状态码:%{http_code} 总耗时:%{time_total}s 解析:%{time_namelookup}s 连接:%{time_connect}s 首字节:%{time_starttransfer}s\n" 接口地址

time_namelookup 是域名解析耗时，time_connect 是建立连接耗时，time_starttransfer 是收到第一个字节的时间，time_total 是总耗时。把这几个数字连起来看，就能判断慢在解析、连接、服务端处理，还是传输阶段。如果总耗时大但首字节时间小，问题多半在数据量或传输上；如果首字节时间本身就大，就要先看服务端处理。

四、常见排查顺序

第一步，先用 -i 确认状态码。返回 2xx 说明请求本身通了，重点看响应体字段是否符合预期；返回 4xx 先自查，返回 5xx 先看服务端日志，不要一上来就改客户端代码。

第二步，按状态码缩小范围。401 或 403 先检查令牌是否过期、请求头有没有带上、权限是否覆盖这条接口；404 先核对路径、版本前缀和占位参数；405 先确认方法是否用错，例如把 POST 写成了 GET；400 先检查 JSON 格式、字段类型和 Content-Type。

第三步，超时或完全无响应时，用 -v 看卡在哪一步。卡在解析可能是域名或解析配置问题，卡在连接可能是地址、端口或防火墙问题，卡在首字节则多半是服务端处理慢或下游依赖慢。

第四步，遇到乱码、截断或解析失败，先看响应头里的 Content-Type 和编码信息，再确认保存和查看方式有没有把二进制当文本处理。最后对比环境：本地能通、线上不通时，逐项对比请求方法、请求头、代理配置和令牌，差异往往就藏在某一个被忽略的细节里。

养成一个习惯：把能复现问题的完整命令、状态码、关键响应头和耗时一起记录下来。这样无论是自己回头排查，还是请同事协助，都不用再从头猜一遍。