stedolan/jq 项目详解：JSON 处理神器 jq 1.6 使用手册

stedolan/jq 项目详解：JSON 处理神器 jq 1.6 使用手册

jq 项目地址: https://gitcode.com/gh_mirrors/jq1/jq

核心概念：jq 过滤器模型

jq 的核心思想是将所有操作视为"过滤器"——每个过滤器接收输入并产生输出。这种设计理念使得 jq 能够以极其简洁的方式处理 JSON 数据。与传统的编程语言不同，jq 通过组合各种过滤器来完成数据处理，而非使用循环和条件语句。

过滤器特性

1. 输入输出模型：每个 jq 过滤器都有明确的输入和输出，即使是字面量如 "hello" 或 42 也是过滤器
2. 组合能力：可以通过管道(|)将多个过滤器连接起来，形成处理链
3. 多结果输出：某些过滤器会产生多个结果（如数组展开），后续过滤器会对每个结果分别处理
4. 并行处理：二元操作（如加法）会自动将相同输入传递给两个子过滤器

基础过滤器详解

1. 身份过滤器 .

最简单的过滤器，原样输出输入内容。常用于 JSON 格式化：

echo '{"name":"John"}' | jq '.'

2. 对象属性访问

• 简单属性：.foo 获取对象的 foo 属性
• 复杂键名：.["foo.bar"] 处理包含特殊字符的键名
• 安全访问：.foo? 在属性不存在时返回 null 而非报错

3. 数组操作

• 索引访问：.[0] 获取第一个元素（支持负数索引）
• 切片操作：.[1:3] 获取子数组（左闭右开区间）
• 展开迭代：.[] 将数组元素展开为多个输出

4. 组合操作

• 逗号操作符：, 合并多个过滤器的输出流
• 管道操作符：| 将左侧输出作为右侧输入

实用命令行选项

jq 提供了丰富的命令行选项来适应不同场景：

输入控制

• -n/--null-input：不使用输入，以 null 作为输入源
• -R/--raw-input：原始文本模式（非 JSON 解析）
• -s/--slurp：将所有输入合并为单个数组处理

输出格式化

• -c/--compact-output：紧凑输出（单行 JSON）
• -r/--raw-output：直接输出原始字符串（去除 JSON 引号）
• -S/--sort-keys：对象按键名排序输出

高级处理

• --stream：流式解析大文件
• --arg/--argjson：向过滤器传递参数
• -e/--exit-status：根据输出结果设置退出状态码

实际应用示例

1. 数据提取

# 提取对象数组中的特定字段
echo '[{"name":"Alice","age":30},{"name":"Bob","age":25}]' | jq '.[].name'

2. 数据转换

# 计算价格平均值
echo '[{"price":10},{"price":20},{"price":30}]' | jq 'map(.price) | add / length'

3. 复杂查询

# 查找满足条件的元素
echo '[{"id":1,"active":true},{"id":2,"active":false}]' | jq '.[] | select(.active)'

最佳实践

1. 引号使用：在 Unix shell 中始终用单引号包裹 jq 表达式
2. 错误处理：使用 ? 操作符避免属性不存在导致的错误
3. 流式处理：对于大文件使用 --stream 选项避免内存问题
4. 模块化：复杂脚本可保存在文件中通过 -f 选项调用

jq 的这种过滤器模型和函数式设计使其成为处理 JSON 数据的多功能工具，通过简单的组合就能完成复杂的数据转换任务。掌握这些基础概念后，可以进一步学习 jq 的高级特性如条件表达式、函数定义和模块系统。

jq 项目地址: https://gitcode.com/gh_mirrors/jq1/jq