古法编程

使用 jq 在命令行高效查询与转换 JSON 数据

解决开发者在处理 API 响应、日志文件或 CLI 工具输出时，面对复杂 JSON 结构难以快速提取关键信息的问题，通过 jq 实现高效的数据过滤与格式转换。

为什么需要这个技能

在现代开发流程中，几乎所有的云服务（AWS, GitHub, Kubernetes）和 API 都会返回 JSON 格式的数据。如果仅靠肉眼观察或使用简单的 grep、sed，在面对深层嵌套的对象或大型数组时会极其低效且容易出错。

jq 是处理 JSON 的行业标准命令行工具，它像 SQL 同样能够对 JSON 进行查询和重塑。掌握 jq 可以让开发者在不编写完整脚本的情况下，通过简单的单行指令完成数据清洗、字段重命名、条件过滤以及格式化输出（如转换为 CSV/TSV），极大地提升自动化运维和开发效率。

适用场景

  • API 数据提取：从 curl 请求的 JSON 响应中提取特定字段（如 Token 或 ID）。
  • 基础设施管理：处理 kubectl、docker inspect 或 gh (GitHub CLI) 的 JSON 输出。
  • 日志分析：过滤结构化 JSON 日志，筛选出满足特定错误条件的记录。
  • 数据流水线：在 Bash 脚本中将 JSON 数据转换为其他格式，以便传递给下一个处理环节。

核心工作流

1. 基础选择与路径访问

通过点号 . 访问对象属性，通过方括号 [] 访问数组。

# 提取根级字段
echo '{"name":"alice","age":30}' | jq '.name'

# 访问嵌套路径
echo '{"user":{"email":"a@b.com"}}' | jq '.user.email'

# 数组切片与索引
echo '[10, 20, 30]' | jq '.[1]'

2. 条件过滤（Select）

使用 select() 函数筛选符合条件的元素。

# 筛选角色为 admin 的用户
echo '[{"role":"admin"},{"role":"user"}]' | jq '[.[] | select(.role == "admin")]'

# 结合数值比较
curl -s https://api.github.com/repos/owner/repo/issues | jq '[.[] | select(.comments > 5)]'

3. 结构转换与映射

将原始 JSON 转换为自定义的结构。

# 提取数组中所有元素的特定字段
jq 'map(.name)' data.json

# 构建新对象并重命名键
jq '[.[] | {username: .name, email_address: .email}]' data.json

4. Shell 集成与实战

在实际脚本中，建议使用 -r 获取原始字符串，并使用 --arg 安全传递变量。

# 将 Shell 变量传递给 jq 避免注入
STATUS="active"
jq --arg s "$STATUS" '[.[] | select(.status == $s)]' data.json

# 实战：从 Kubernetes 提取 Pod 名称和状态
kubectl get pods -o json | jq '.items[] | {name: .metadata.name, status: .status.phase}'

下载和安装

下载 jq 中文版 Skill ZIP

解压后将目录放入你的 AI 工具 skills 文件夹，重启工具后即可使用。具体路径参考内附的 USAGE.zh.md。

你可能还需要

暂无推荐