jqlang/jq 1.4 使用手册详解：JSON处理利器

jqlang/jq 1.4 使用手册详解：JSON处理利器

jq Command-line JSON processor 项目地址: https://gitcode.com/gh_mirrors/jq/jq

概述

jq 是一个轻量级且功能强大的命令行 JSON 处理器，它采用类似 Unix 管道的过滤机制来处理 JSON 数据。jq 的核心思想是将 JSON 处理过程分解为一系列过滤器(filter)的组合，每个过滤器接收输入并产生输出。

基本概念

过滤器(Filter)模型

在 jq 中，所有操作都是过滤器。即使是简单的值如 "hello" 或 42 也是过滤器 - 它们接收输入但总是产生相同的字面量作为输出。这种设计使得 jq 具有高度的一致性。

过滤器可以通过多种方式组合：

• 管道(|)：将一个过滤器的输出作为下一个过滤器的输入
• 逗号(,)：并行运行多个过滤器并合并结果
• 数组构造([])：将多个结果收集到数组中

与常规编程语言的区别

在其他语言中需要通过循环和迭代完成的操作，在 jq 中通常只需将过滤器组合起来即可。例如，计算数组平均值可以简单地表示为 add / length，这得益于 jq 会将相同的输入同时传递给 add 和 length 过滤器。

基本使用方法

命令行语法

jq [选项] <过滤器> [文件...]

如果没有指定文件，jq 会从标准输入读取 JSON 数据。多个 JSON 对象可以用空格分隔。

常用选项

jq 提供了丰富的选项来控制输入输出行为：

• 输入控制：

  • -n/--null-input：不使用输入，以 null 作为输入
  • -R/--raw-input：不解析输入为 JSON，每行作为字符串处理
  • -s/--slurp：将所有输入读取为单个数组

• 输出控制：

  • -c/--compact-output：紧凑输出（每行一个 JSON 对象）
  • -r/--raw-output：直接输出字符串内容（不带引号）
  • -S/--sort-keys：按键名排序输出对象字段

• 变量传递：

  • --arg name value：定义变量 $name 值为 value
  • --argfile name file：从文件读取变量值

基础过滤器详解

1. 身份过滤器 .

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

echo '{"foo":42}' | jq '.'

2. 字段访问 .foo, .["foo"]

访问对象的字段：

• .foo 是 .["foo"] 的简写形式
• 如果字段名包含特殊字符或数字开头，必须使用 .["foo"] 形式
• 支持链式访问：.foo.bar 等同于 .foo | .bar

3. 安全访问 .foo?

与 .foo 类似，但当输入不是对象时不会报错，而是返回 null。

4. 数组索引 .[index]

• 数组从 0 开始索引
• 支持负索引（从末尾开始计数）
• 支持切片语法 .[start:end]（包含 start，不包含 end）

5. 展开操作 .[]

将数组或对象的所有元素/值展开为多个输出：

• 对于数组：输出每个元素
• 对于对象：输出每个值

6. 逗号操作符 ,

并行执行多个过滤器，按顺序输出所有结果：

.foo, .bar  # 输出 foo 和 bar 字段

7. 管道操作符 |

将左侧过滤器的输出作为右侧过滤器的输入：

.[] | .name  # 输出数组中每个元素的 name 字段

数据结构构造

1. 数组构造 []

将多个结果收集到数组中：

[.user, .projects[]]  # 创建包含用户和所有项目的数组

2. 对象构造 {}

构造 JSON 对象：

• 完整语法：{"key": expression}
• 简写语法：当键名与字段名相同时可使用 {user, title}
• 支持动态键名：{(expression): value}

内置运算符和函数

加法运算符 +

根据操作数类型有不同的行为：

• 数字：算术加法
• 数组：数组合并
• 字符串：字符串连接
• 对象：对象合并（相同键时右侧值覆盖左侧）

注意：jq 不会进行隐式类型转换，类型不匹配会报错。

使用技巧

1. 格式化 JSON：

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

2. 提取特定字段：

   jq '.user.name' data.json
   

3. 处理数组：

   jq '.items[] | {id, name}' items.json
   

4. 构造新 JSON：

   jq '{username: .user, projects: [.projects[] | select(.active)]}' data.json
   

5. 条件处理：

   jq 'if .age > 18 then "adult" else "minor" end' people.json
   

总结

jq 提供了一种声明式的方式来处理和转换 JSON 数据，其强大的过滤器和组合能力使得复杂的 JSON 处理变得简单直观。通过掌握基本过滤器和操作符，可以高效地完成各种 JSON 处理任务，是开发者和系统管理员处理 JSON 数据的理想工具。

jq Command-line JSON processor 项目地址: https://gitcode.com/gh_mirrors/jq/jq