JQ 入门：命令行 JSON 处理利器

JQ 是一个轻量级的命令行 JSON 处理器。无论你是处理 REST API 返回的数据，还是分析日志文件中的 JSON 结构，JQ 都能帮你快速提取、转换和格式化数据。这里带你从零开始，掌握 JQ 的核心用法。

什么是 JQ？

JQ 是一个轻量级的命令行 JSON 处理器。它像 sed 或 awk 对于文本一样，但专门为 JSON 数据设计。你可以通过管道（|）将 JSON 文档传入 JQ，它会对数据应用你指定的过滤器，然后将结果输出到标准输出。

JQ 是一个独立的可执行文件，安装非常简单——无论你用的是 Linux、macOS 还是 Windows，都能轻松安装。

最简单的过滤器是恒等过滤器（identity filter），即 .，它会原样返回输入内容：

echo '{ "key1": { "key2": "value1" } }' | jq '.'

这个过滤器最适合用来美化打印 JSON 文档。

核心概念：对象标识符索引 (Object Identifier-Index)

JQ 允许你将 JSON 文档当作 JavaScript 对象来处理，使用 . 运算符逐级访问内部属性。

curl -s https://api.github.com/repos/stedolan/jq | jq '.name'
curl -s https://api.github.com/repos/stedolan/jq | jq '.description'

你可以层层深入：

curl -s https://api.github.com/repos/stedolan/jq | jq '.owner.login'

这种访问方式的通用写法是：

.key.subkey.subsubkey

数组索引与切片

当你处理的是 JSON 数组时，JQ 同样支持数组索引。以 GitHub Issues API 为例：

curl -s https://api.github.com/repos/stedolan/jq/issues?per_page=5 | jq '.[0]'

JQ 还支持一些便捷语法：

• 单侧范围：.[2:] 获取从索引 2 开始到末尾的所有元素
• 负数索引：.[-1] 获取最后一个元素
• 组合使用：结合对象索引，如 .[0].title

获取数组中的所有元素

使用 .[] 可以遍历数组中的所有元素：

curl -s https://api.github.com/repos/stedolan/jq/issues?per_page=5 | jq '.[].title'

这会返回所有 issue 的标题，每行一个。

小技巧：如果希望输出原始字符串（不带引号），可以加上 -r 参数：

curl -s ... | jq -r '.[].title'

数组构造器

使用 .[] 获取集合时，JQ 会以换行分隔的方式返回每个元素。如果你希望将它们包装回一个 JSON 数组，只需在外层加上 []：

curl -s https://api.github.com/repos/stedolan/jq/issues?per_page=5 | jq '[.[].title]'

这类似于 JavaScript 中把值放进数组的方式。

选择多个字段

使用逗号分隔可以一次性选择多个字段：

curl -s https://api.github.com/repos/stedolan/jq/issues?per_page=2 | jq '.[].title, .[].number'

如果要改变顺序，可以先用 [] 解包，再通过管道串联：

curl -s ... | jq '.[] | .title, .number'

对象构造器

当你需要将选中的值重新组织成 JSON 对象时，可以使用对象构造器 {}：

echo '["Adam", "Gordon", "Bell"]' | jq '{ first_name: .[0], last_name: .[2] }'

回到 GitHub API 的例子，将标题和编号组合成对象数组：

curl -s https://api.github.com/repos/stedolan/jq/issues?per_page=2 | jq '[ .[] | { title: .title, number: .number } ]'

通用写法：

{ key1: jq_filter, key2: jq_filter }

内置函数与排序

JQ 内置了许多实用的函数，它们大多与 JavaScript 的数组方法类似：

• sort — 排序
• length — 获取长度
• map — 映射转换

将 labels 排序：

curl -s https://api.github.com/repos/stedolan/jq/issues/2289 | jq '{ title: .title, number: .number, labels: .labels | sort }'

统计 labels 数量：

curl -s ... | jq '{ title: .title, number: .number, labels: .labels | length }'

管道与过滤器

JQ 的管道（|）概念与 UNIX shell 的管道类似——将前一个过滤器的输出作为下一个过滤器的输入。

echo '{ "title": "JQ Select" }' | jq '.title | length'

通过管道，你可以将多个简单的操作组合成复杂的转换：

.key1.subkey2[] | sort
.key2.subkey | length
.key3 | floor | tostring | length

进阶：map 与 select

map 是 [ .[] | ... ] 的简写形式，它解包数组、应用过滤器，然后重新包装回数组。

结合 select 函数可以按条件筛选数据。select 接收一个布尔表达式，只返回匹配的元素，类似于 SQL 中的 WHERE 子句或 JavaScript 中的 Array.filter()：

curl -s https://api.github.com/repos/stedolan/jq/issues?per_page=100 | jq 'map({ title: .title, number: .number, labels: .labels | length }) | select(.labels > 0)'

这条命令做了多件事情：映射对象结构、计算标签数量、过滤出有标签的 issue。虽然没有用 SQL，但它组合了三个对象索引、两个 map、两个管道和一个 select 谓词。

知识回顾

• 对象/数组索引：用 .key[0].subkey[2:3].subsubkey 选取元素
• 对象构造器：用 [ { key1: .key1, key2: .key2 } ] 重新包装
• 管道：用 | 串联过滤器，map({ ... }) | select(...)
• 内置函数：sort、length、map、select 等

如何真正掌握 JQ？

1. 动手练习：推荐 jq play 交互式练习平台，里面有大约 20 道练习题
2. 刻意使用：遇到需要处理 JSON 的任务时，优先选择 JQ
3. 逐步深入：学习递归下降、变量声明、函数定义等高级特性

JQ 的查询语言本质上是一门完整的编程语言——你可以用它进行 JSON 与 JSON 的互相转换，定义自己的函数，甚至实现素数生成等算法。但对于日常使用，掌握本文介绍的选取、过滤、映射和组合这些基础操作，就已经能应对绝大多数场景了。

不再需要每次处理 JSON 都去搜索引擎查 JQ 用法——把这篇文章收藏起来，当你下次面对一堆 JSON 数据时，JQ 会是你最得力的助手。