这条路径解决什么
调接口排查与取数时，标准组合是 curl 负责取、jq 负责解析：curl -sS 静默但保留错误、-o 把响应体落盘、-w 单独取状态码，jq 用路径表达式抽出需要的字段。把「状态码」与「响应体」分开处理，是这类脚本可靠的关键——很多问题其实是网关返回了 HTML 错误页而不是 JSON。
基本信息
| 适用场景 | 从接口响应里提取字段、做巡检与数据核对 |
|---|---|
| 核心工具 | curl -sS -o 文件 -w 格式、jq -r 输出原始字符串 |
| 退出码约定 | curl -f 让 HTTP 4xx 与 5xx 返回非零；jq 解析失败也返回非零 |
| 常用选项 | jq -r 去引号、-c 紧凑输出、-e 让结果为空时返回非零 |
| 前置检查 | 先落盘原始响应，再解析；避免边取边解析导致现场丢失 |
典型使用场景
- 健康巡检：取 status 字段判断服务是否正常
- 数据核对：从接口拉列表，用 jq 转成制表符分隔再交给 column 对齐
- 排障取证：先把响应体与状态码一起存档，再离线分析
- 批量校验：对一批接口循环取值，统计异常项
- 与监控对接：把接口返回的数值转成监控可直接消费的格式
基础提取
基础提取
curl -sS -o /tmp/r.json -w '%{http_code}\n' https://api.example.com/health # 状态码与响应体分开
curl -sSf -o /tmp/r.json https://api.example.com/health # HTTP 错误直接非零退出
jq -r '.data.host, .data.uptime' /tmp/r.json # 抽多个字段
jq -r '.items[] | [.id, .name, .status] | @tsv' /tmp/r.json | column -t # 列表转表格
jq -e '.status == "ok"' /tmp/r.json > /dev/null # 作为脚本判据jq 常用表达式
| 表达式 | 作用 | 注意 |
|---|---|---|
| .data.host | 按路径取值 | 键不存在时返回 null，不是报错 |
| .items[] | 迭代数组元素 | 对 null 迭代会报错，先判空 |
| select(.x > 1) | 按条件过滤 | 常与数组迭代组合使用 |
| @tsv 与 @csv | 转成制表符或 CSV | 配 -r 使用，便于 column 对齐 |
| // 默认值 | 左边为 null 时取右边 | 用于补齐缺失字段 |
| to_entries | 把对象转成键值对数组 | 适合遍历未知键名 |
| -e | 按结果决定退出码 | 脚本里判断条件是否成立 |
curl -f 让 HTTP 状态码大于等于 400 时返回非零退出码，脚本判断成功失败比解析状态码更可靠；-sS 组合表示静默进度但保留错误信息，是脚本里的推荐写法。
管道里 jq 失败会被后面的命令掩盖：curl 的失败状态被丢弃，最终退出码来自管道最后一个命令。脚本开头加 set -o pipefail，才能让中间环节的失败真正暴露出来。
解析前先摸清结构：jq type 判断顶层是对象还是数组，jq keys 看有哪些字段名。字段名里含连字符、点号或空格时，点号语法不成立，要改用 .["field-name"] 这种带方括号与引号的写法。