用 curl 调试接口：从状态码、请求头到超时排查

接口调不通的时候，很多人第一反应是改代码、重启服务，结果绕了一大圈才发现问题出在请求本身。curl 是每个后端和前端开发者都值得随身携带的调试工具：它不依赖浏览器，不依赖图形界面，一条命令就能把请求发出去、把响应原样拿回来。下面按排查顺序，讲清楚用 curl 调试接口的常用方法。

一、先看状态码，别只看有没有返回

最基础的命令是 curl -i https://example.com/api/users 。-i 会同时输出响应头和响应体，状态码就在第一行。200 不代表业务成功，还要看响应体里的业务码；404 先确认路径拼写和路由有没有注册；405 说明方法不对，例如把 POST 写成了 GET；500 则要去服务端日志里找堆栈，而不是在客户端反复重试。需要只看状态码时，可以用 curl -o /dev/null -s -w "%{http_code}" 加地址，输出干净，适合写进脚本做健康检查。

二、用 -v 看清请求到底发了什么

当状态码和预期不一致时，加上 -v 可以看到 DNS 解析、TLS 握手、发送的请求头和收到的响应头。很多“明明传了参数却没生效”的问题在这里就现形了：请求头里没有 Authorization，或者 Content-Type 是表单而不是 JSON，或者请求被重定向到了登录页。排查时建议先确认三件事：地址有没有多余的斜杠或参数编码错误，请求头是否齐全，响应头里的 Content-Type 和实际解析方式是否匹配。

三、POST 请求要讲清格式

发 JSON 时，常用写法是 curl -X POST -H "Content-Type: application/json" -d '{"name":"demo"}' 加地址。这里容易踩的坑有三个：一是忘记 -H 导致服务端按表单解析；二是 shell 对引号的处理，JSON 里有双引号时外层要用单引号；三是中文或特殊字符没有正确编码。发表单时则用 -d "name=demo" 并保持默认的表单类型，不要两种格式混用。返回结果建议先用管道交给 jq 或 python -m json.tool 格式化，字段结构一目了然。

四、超时和慢接口要分开看

接口一直转圈不返回，先区分是连接不上还是响应太慢。--connect-timeout 限制建立连接的时间，--max-time 限制整个请求的最长时间。连接阶段就超时，往往是域名解析、端口没放行或服务根本没启动；连接成功但响应慢，则要看服务端处理耗时、数据库查询和下游依赖。还可以用 -w 输出 time_connect、time_starttransfer 和 time_total，把“慢在哪一段”量化出来，而不是凭感觉猜。

五、一个可复用的排查清单

第一步确认地址和方法，第二步用 -i 看状态码和响应头，第三步用 -v 核对请求头和重定向，第四步检查请求体格式和编码，第五步用超时参数定位慢的环节，第六步对照服务端日志确认业务码。按这个顺序走，大多数接口问题都能在几分钟内定位到某一层。

最后提醒一点：调试时不要把真实的密钥、Token 或用户密码贴进公开的命令记录或截图里。可以用占位符代替真实凭证，确认问题后再在本地用真实凭证复现。把 curl 用熟，接口联调就不再是玄学，而是一步步可以验证的过程。