接口调不通别先抓狂，curl + jq 一行命令把问题钉死

联调接口时，最耗时的不是修 bug，而是定位"到底是哪一层的问题"。网络通不通、鉴权对不对、返回的数据长什么样——与其在代码里加一堆 print，不如直接用 curl + jq 在终端里把问题钉死。下面是我常用的几板斧。

一、先确认"能通"

curl -I https://api.example.com/health

-I 只取响应头，不下载正文，看状态码是 200 还是 401/403/500，半秒钟知道服务活没活。超时就加 --max-time 10，避免卡死。HTTPS 证书问题先用 -k 绕过验证，确认是证书问题再修，别一上来就怀疑代码。

二、带参数的请求一次写对

GET 查数据、POST 提交数据，参数写法不同：

curl -X POST https://api.example.com/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"test","role":"dev"}'

新手常踩的坑：-d 默认发的是 POST 但 Content-Type 是表单类型，发 JSON 必须显式声明 header。服务器报 415 Unsupported Media Type，九成是这行漏了。

三、jq 把 JSON 压成"人话"

接口返回几十 KB 的 JSON，直接看是灾难。用 jq 只取关心的字段：

curl -s https://api.example.com/users/1 | jq '.data.name, .data.email'

-s 是静默模式，不输出进度条。排错三件套：jq ‘.’ 格式化、jq ‘keys’ 看顶层字段、jq ‘.list | length’ 数数组长度。返回体里混了 HTML（比如鉴权失败跳登录页），第一眼就发现问题不在业务逻辑。

四、真实踩坑两例

1. 环境变量里的换行：TOKEN 从文件读出来带了 \n，Authorization 头就失效了，服务器一直 401。用 echo “$TOKEN” | xxd 看一眼，tr -d ‘\n’ 处理后再用。联调半小时的教训，五秒钟的命令。
2. 代理"帮忙"改了请求：公司内网走代理时，代理给请求加了自己的 header 导致签名失败。curl 加 --noproxy ‘*’ 直连一试，问题立刻复现/消失，责任边界瞬间清晰。

五、小结

curl 负责"发"，jq 负责"看"，组合起来就是终端里的 Postman。建议把常用命令存成 shell 函数或 alias，联调时随叫随到。记住顺序：先看状态码，再看鉴权，最后看返回体结构——九成接口问题死在这三步里。

（全文约 800 字，原创，未在任何平台发表过）