# 用 jq 在终端里筛选、重塑客户 API 返回的 JSON

> 客户问“超过 500 的失败订单有多少”，最快的答案可能只是一条命令，用不着打开 notebook。

原文: https://fdetimes.net/zh/tools/jq-filter-reshape-json-terminal/

客户会议开到半小时，运营团队问了一个很平常的问题：这周金额超过 500 的支付失败有多少笔，分别是哪些客户？

数据就在他们的 API 里，返回的是一段几千行的 JSON。你可以打开 notebook 写个脚本，也可以敲一条命令，在会议结束前把 CSV 发过去。

这条命令通常就是 jq。官网 jqlang.org 称它是一个“轻量且灵活”的命令行 JSON 处理器，并把它比作针对 JSON 的 `sed`。前线部署工程师（FDE）每天都要阅读客户系统里陌生的数据载荷，jq 是最值得尽早掌握的工具之一。

## 为什么适合客户的机器

客户的机器很少有你想要的环境。

它可能是一台管控严格的堡垒机，装不了 Python 包，也没有 root 权限。jq 用可移植的 C 编写，不依赖任何运行时，只需要一个可执行文件。它采用 MIT 许可证发布，需要申请在别人的基础设施上安装工具时，这一点会有帮助。

## 一切皆过滤器

想熟练使用 jq，需要先理解一个概念。jq 1.8 手册是这样定义的：jq 程序是一个“过滤器”，接收输入，产生输出。过滤器之间用 `|` 串联，和 shell 管道一样，数据从左向右流动。

假设客户的 API 返回了这样一个文件 `orders.json`：

```json
{"items": [
  {"id": "A1", "status": "failed", "amount": 1200, "cust_id": "C9"},
  {"id": "A2", "status": "paid",   "amount": 800,  "cust_id": "C3"},
  {"id": "A3", "status": "failed", "amount": 90,   "cust_id": "C9"}
]}
```

第一步是把数组拆成单条记录，再只保留失败的订单。`select(f)` 函数正好做这件事：`f` 为真时原样返回输入，否则丢弃。

```bash
jq '.items[] | select(.status == "failed")' orders.json
```

结果是 A1 和 A3 两笔订单。从左往右读：进入 `items` 数组，遍历每个元素，保留状态为 failed 的那些。

## 从 shell 传入阈值，不必和引号较劲

今天的阈值是 500，明天可能变成 1000，所以不要写死。笨办法是把 shell 字符串拼进 jq 程序中间，然后和单引号、双引号缠斗。手册给出了更干净的做法：`--arg` 和 `--argjson` 会把值作为预定义变量传入程序。

```bash
jq --argjson min 500 \
  '.items[] | select(.status == "failed" and .amount > $min)' orders.json
```

现在只剩 A1。三条示例记录可以靠眼睛数；面对几千条真实记录，下一步会同时给出数量和清单。

## 从 JSON 到客户打得开的文件

客户的运营团队不看 JSON，他们打开的是电子表格。`@csv` 格式接收一个数组，输出一行 CSV：字符串用双引号包裹，其中的引号会被双写。所以你要做的，是构造一个恰好包含所需列的数组，再交给 `@csv`。

```bash
jq -r --argjson min 500 \
  '.items[] | select(.status == "failed" and .amount > $min)
   | [.id, .cust_id, .amount] | @csv' orders.json > failed.csv
```

文件 `failed.csv` 只有一行：`"A1","C9",1200`。一行就是一笔订单，第二列说明是哪个客户。问题的两部分都有了答案。

有时麻烦出在字段名上：客户叫 `cust_id`，你的系统叫 `customer_id`。`to_entries` 和 `with_entries` 这对函数能在对象和键值对数组之间转换，因此不必重新列出所有字段就能重命名某个键：

```bash
jq '.items[] | with_entries(.key |= if . == "cust_id" then "customer_id" else . end)' orders.json
```

**要点:** 客户在会上提的问题，应该在会议结束前得到答案。

## 新手常犯的三个错误

第一，混淆 `--arg` 和 `--argjson`。`--arg` 传入的是字符串，`--argjson` 传入的是 JSON 编码的值，所以 `500` 仍然是数字。拿 `.amount` 和字符串 `"500"` 比较，得不到想要的结果，而且这种 bug 在演示中途很难发现。

第二，把整个对象交给 `@csv`。手册明确规定，`@csv` 的输入必须是数组，所以 `{"id": "A1", ...}` 要先变成 `[.id, .cust_id, .amount]`，电子表格里的列顺序也正是由这一步确定的。

第三，以为 `select` 会修改数据。它只负责保留或丢弃，通过的记录原封不动。要改变数据形状，就在 `|` 后面再加一个过滤器。

## 局限：它是一门语言，不是捷径

Wikipedia 把 jq 描述为命令行工具，同时也是一门领域专用的函数式编程语言。这让它表达能力很强，但一段很长的 jq 程序，和任何语言写的代码一样难读。

一旦命令写到十行、条件层层嵌套，接手项目的同事维护起来，会比一个有测试的 Python 脚本更吃力。

实用的原则是：jq 用于探索和当场回答问题，比如查看数据载荷、筛选、导出文件。当这段逻辑变成客户数据管道中反复执行的步骤，就把它迁到经过测试和评审的代码里。

## 先学什么，以及如何写进简历

合理的学习顺序是：字段访问和数组遍历，用 `|` 串联，然后是 `select`、`--argjson`、`@csv`，最后是 `with_entries`。最好的练习，是拿手头项目的一个 API 响应，把上面的步骤原样走一遍：筛选失败记录，用 `--argjson` 传入阈值，导出 CSV，再重命名一个字段。

不要只在技能栏里写上“jq”。在作品集仓库里放一份 runbook，附上几条检查数据的 jq 命令，并简短说明每条命令回答什么问题，招聘方就能看出你能读懂、排查不属于自己的数据。

上面那条导出 CSV 的命令就是很好的起点：真实的问题，真实的数据，真实的数字。

**本周动手试试:**

- 从当前项目中取一个真实的 API 响应，写一条 jq 命令筛选出失败记录，并导出为 CSV。
- 找一个只做 JSON 筛选的简短 Python 脚本，改写成一行 jq，再比较哪个更好读。
- 在作品集项目的 README 或 runbook 里加一节“快速检查”，收录几条 jq 命令。

## 信源

- [jq](https://jqlang.org/)

- [jq 1.8 Manual](https://jqlang.org/manual/)

- [GitHub - jqlang/jq: Command-line JSON processor](https://github.com/jqlang/jq)

- [jq (programming language) - Wikipedia](https://en.wikipedia.org/wiki/Jq_(programming_language))
