curl + jq 接口调试实战：把混乱 JSON 快速看明白

调接口时，很多人第一反应是打开浏览器或接口工具。它们当然好用，但在服务器、CI 脚本、远程排查场景里，命令行更直接：一条 curl 发请求，一条 jq 把 JSON 筛成你真正想看的字段。

本文用一个用户列表接口做例子，演示如何从“满屏 JSON 看不清”走到“关键字段一眼看到”。同时也会给出接口失败时的排查顺序：先看状态码，再读响应体，再查请求头和超时。

摘要

curl 负责发起 HTTP 请求，jq 负责整理 JSON。组合使用时，可以快速完成接口连通性检查、字段提取、错误定位和脚本化验证。核心思路是：先拿到原始响应，再用 jq 逐层筛选，最后把排查步骤固定成可复用命令。

适合人群

适合后端、前端、测试、运维同学。只要你经常排查接口返回、线上配置、第三方回调、JSON 日志，就能把这套方法放进日常工作流里。

目录

• 先确认接口能不能通
• 用 jq 把 JSON 筛成可读结果
• 接口失败时按四步排查
• 把常用命令整理成脚本片段
• 常见问题和总结

一、先确认接口能不能通

第一步不要急着写复杂筛选，先确认接口是否能正常返回。下面这个例子用 -s 关闭进度条，用 -i 带上响应头，方便同时看状态码和响应体。

curl -s -i "https://api.example.com/users?page=1"

如果接口需要认证，把请求头带上即可。实际排查时不要把真实 token 写进共享文档或提交到仓库，可以从环境变量读取。

curl -s \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Accept: application/json" \
  "https://api.example.com/users?page=1"

这一步只回答一个问题：请求有没有到达目标服务，服务有没有给出 JSON。确认通了以后，再开始筛字段。

二、用 jq 把 JSON 筛成可读结果

假设接口返回结构大致如下：

{
  "code": 0,
  "data": [
    {"id": 101, "name": "Alice", "status": "active", "role": "admin"},
    {"id": 102, "name": "Bob", "status": "disabled", "role": "user"}
  ],
  "meta": {"page": 1, "total": 2}
}

直接看完整 JSON 还行，但线上接口字段一多就会很累。可以先用 jq 美化输出：

curl -s "https://api.example.com/users?page=1" | jq '.'

再提取列表里的几个关键字段：

curl -s "https://api.example.com/users?page=1" \
  | jq '.data[] | {id, name, status}'

如果想把结果变成更适合终端查看的一行一条，可以用 -r 输出纯文本：

curl -s "https://api.example.com/users?page=1" \
  | jq -r '.data[] | [.id, .name, .status] | @tsv'

这张图对应完整流程：先请求接口，再拿到返回 JSON，然后筛出字段，最后只看调试需要的结果。它的好处是把“数据很全”和“我只关心少数字段”分开处理。

常用 jq 写法

# 读取顶层字段
jq '.code'

# 读取数组长度
jq '.data | length'

# 过滤指定状态
jq '.data[] | select(.status == "active")'

# 给字段改名，方便贴到排查记录里
jq '.data[] | {user_id: .id, username: .name, state: .status}'

建议先从简单路径开始写，不要一上来就写很长的表达式。每次只加一层筛选，能减少排查时的误判。

三、接口失败时按四步排查

接口失败时，不建议只盯着“报错了”三个字。比较稳定的顺序是：看状态码、读响应体、查请求头、修复后重试。

1. 看状态码

用 -w 单独输出 HTTP 状态码，适合脚本和排查记录。

curl -s -o /tmp/users-body.json \
  -w "status=%{http_code} time=%{time_total}\n" \
  "https://api.example.com/users?page=1"

2xx 说明请求基本成功；4xx 多半是参数、权限、路径问题；5xx 更偏服务端异常或依赖异常。状态码不是最终答案，但能把方向先分出来。

2. 读响应体

状态码只告诉你大类，响应体经常会告诉你具体原因。

jq '{code, message, detail}' /tmp/users-body.json

如果响应体不是 JSON，jq 会报解析错误。这时反而说明要先确认服务是否返回了 HTML 错误页、网关提示页，或者压根不是预期接口。

3. 查请求头

很多接口问题不是业务参数错，而是请求头没带全，比如认证、内容类型、灰度标记、租户标识。

curl -s -i \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  "https://api.example.com/users?page=1"

如果接口要求 JSON 请求体，建议显式带上 Content-Type，不要依赖默认行为。

4. 修复后重试

重试前要先修复原因，例如补参数、换 token、改路径、延长超时。不要在原因未知时疯狂重试，否则可能把对方服务或自己的网关压得更重。

curl -s --connect-timeout 3 --max-time 10 \
  -H "Authorization: Bearer ${API_TOKEN}" \
  "https://api.example.com/users?page=1" \
  | jq '.data[] | {id, name, status}'

四、把常用命令整理成脚本片段

当同一个接口要反复排查时，可以把地址、请求头、输出格式整理成一个小片段。下面示例把接口响应保存到文件，再用 jq 输出关键信息。

API_BASE="https://api.example.com"
API_PATH="/users?page=1"
BODY_FILE="/tmp/users-body.json"

curl -s -o "${BODY_FILE}" \
  -w "status=%{http_code} time=%{time_total}\n" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  "${API_BASE}${API_PATH}"

jq -r '.data[] | [.id, .name, .status] | @tsv' "${BODY_FILE}"

这个片段不追求复杂，只解决一个问题：同样的接口，同样的请求头，同样的输出方式，下一次排查不用从零开始敲。

常见问题

1. jq 报 Cannot index array 怎么办？

说明你把对象路径和数组路径写混了。先运行 jq '.' 看清结构，再决定是用 .data.name 还是 .data[] | .name。

2. 为什么 curl 返回的是 HTML？

常见原因是路径写错、网关拦截、登录态过期、服务返回错误页。先加 -i 看响应头，再看状态码和 Content-Type。

3. token 不想显示在历史记录里怎么办？

可以把 token 放到环境变量里，或者从本地安全配置读取。不要把真实 token 写到文章、日志、脚本仓库或群聊截图里。

总结

curl + jq 的组合适合快速、稳定、可复用地调试 JSON 接口。先用 curl 拿到响应，再用 jq 筛关键字段；遇到失败时按“状态码、响应体、请求头、修复重试”的顺序排查。熟练以后，它会成为接口调试里非常顺手的一把小工具。