Linux 与服务器运维 / 系统课时

用 jq 解析接口返回的 JSON

用 jq 解析接口返回的 JSON

运维脚本经常需要从健康检查、发布接口或监控 API 中提取少数字段。直接用 grep、cut 解析 JSON 很脆弱,字段顺序、缩进或转义一变化就可能出错;jq 能按 JSON 结构选择、过滤和重组数据,并用退出状态参与自动化判断。

学习目标

  • 使用 jq 选择对象字段、数组元素和嵌套值
  • 用 select、管道和对象构造完成过滤与重组
  • 让接口健康检查同时验证 JSON 内容与命令退出状态

从字段选择开始

假设健康检查接口返回下面的数据:

json
{
  "status": "UP",
  "service": "order-api",
  "checks": [
    {"name": "db", "status": "UP"},
    {"name": "redis", "status": "DOWN"}
  ]
}

将它保存为 health.json 后,可以直接选择需要的字段:

bash
jq -r '.service, .status, .checks[1].status' health.json

预期输出:

text
order-api
UP
DOWN

-r 会把 JSON 字符串输出为原始文本,便于赋给 Shell 变量;不加 -r 时字符串会保留 JSON 双引号。数组下标从 0 开始。

过滤数组中的目标项

select(...) 会保留满足条件的元素,常用于从告警、实例或检查项数组中找出异常对象。

bash
jq -r '.checks[] | select(.status != "UP") | .name' health.json

预期输出:

text
redis

执行过程是先用 .checks[] 逐个展开数组元素,再由 select 过滤,最后输出异常项的 name。这种方式不会受到 JSON 缩进、空格或字段顺序变化的影响。

重组为脚本真正需要的数据

接口原始响应通常包含很多字段,脚本只需少量稳定信息。可以直接用 jq 构造一个新对象,把后续处理限定在真正需要的数据上。

bash
jq '{service: .service, overall: .status, failed: [.checks[] | select(.status != "UP") | .name]}' health.json

预期输出:

json
{
  "service": "order-api",
  "overall": "UP",
  "failed": [
    "redis"
  ]
}

对象构造中的值仍然可以使用 jq 表达式。方括号会把表达式产生的多条结果收集成数组,适合一次性输出失败实例、异常节点或未通过的检查项。

用退出状态驱动健康检查

只打印字段还不够,自动化脚本必须得到明确的成功或失败状态。jq -e 会根据最终结果设置退出状态;表达式结果为 false 或 null 时返回非零,因此很适合直接放入 Shell 条件判断。

bash
response='{"status":"UP","checks":[{"name":"db","status":"UP"},{"name":"redis","status":"UP"}]}'
if jq -e '.status == "UP" and all(.checks[]; .status == "UP")' >/dev/null <<<"$response"; then
  echo "healthy"
else
  echo "unhealthy"
fi

预期输出:

text
healthy

如果把任意检查项的 status 改为 DOWN,预期输出会变为:

text
unhealthy

这种写法比先提取多个字符串再交给 Shell 比较更紧凑,也能把表达式不成立直接收敛到失败路径。

处理真实接口响应

调用 HTTP 接口时,要同时验证请求本身和 JSON 内容。下面示例假设接口返回包含 status 字段的健康检查 JSON,<PORT> 需要替换为实际端口:

bash
set -o pipefail
url='http://127.0.0.1:<PORT>/health'
if curl -fsS "$url" | jq -e '.status == "UP"' >/dev/null; then
  echo "service is up"
else
  echo "service check failed" >&2
  exit 1
fi

预期结果:

text
当 HTTP 请求成功且响应中的 status 为 UP 时,输出 service is up,并以 0 退出;HTTP 请求失败、返回 4xx/5xx,或 jq 判断结果为 false/null 时,输出 service check failed,并以 1 退出。

curl -f 让 HTTP 4xx/5xx 进入失败路径,-sS 减少正常输出但保留错误信息,pipefail 则防止前面的 curl 失败被后续命令状态掩盖。

jq 的核心价值不是把 JSON 格式化得更漂亮,而是让脚本围绕结构化数据工作:先选择,再过滤,再重组,最后使用 -e 把业务条件转换成可供 Shell 判断的退出状态。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 jq 解析接口返回的 JSON

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通