用 jq 在命令行里优雅处理 JSON

日常对接 API、读配置、查日志时，JSON 几乎无处不在。很多人会把整段响应丢进 Python 或 Node 里解析，其实在 shell 里用 jq 往往更快、更稳，也更适合写进脚本和 CI。

为什么值得学 jq

jq 是专门处理 JSON 的命令行工具：过滤字段、改结构、聚合统计都能一行搞定。它不依赖语言运行时，管道友好，输出可直接喂给下一道命令。装好后（Debian/Ubuntu 上是 apt install jq），所有环境行为一致。

三个最常用的过滤器

假设接口返回：

{"users":[{"id":1,"name":"Ada","active":true},{"id":2,"name":"Bob","active":false}],"total":2}

取顶层字段：

curl -s https://example.com/api | jq '.total'

只保留活跃用户的名字：

... | jq '[.users[] | select(.active) | .name]'

把数组压成一行 CSV 风格：

... | jq -r '.users[] | [.id, .name] | @csv'

-r 表示 raw 输出，去掉引号，方便直接当参数用。

写脚本时的几个习惯

1. 先校验再加工：jq empty file.json 能在语法错误时立刻退出非零，适合放在流水线最前面。
2. 用 --arg / --argjson 传外部变量，不要字符串拼接拼进过滤器，避免注入和转义坑。
3. 大文件用流式：jq --stream 或配合 ijson 一类工具，别一次把几十兆 JSON 全载进内存。
4. 和 curl 组合：curl -fsS ... | jq -e '.ok == true'，-e 让断言失败时返回非零，CI 会自然红灯。

一个实用小例子：从 GitHub/GitCode API 抽标题

curl -fsS -H "Authorization: Bearer $TOKEN" \
  "https://api.example.com/repos/foo/bar/issues?state=open" \
  | jq -r '.[] | "#\(.number) \(.title)"'

一行就能得到可读的 Issue 列表，再 | head 或写进日报都不费劲。

小结

jq 学起来成本低，却能把大量「临时写个解析脚本」的工作压缩成管道。下次再面对嵌套 JSON，先想想能不能用 .[] | select(...) | .field 解决——往往比打开 IDE 更快。

（本文仅作技术分享，不含任何账号、密钥或内网地址。）