FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

工具

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

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

分享微博

要点速览

  • jq 是用 C 编写的单个可执行文件,不依赖任何运行时,可以直接装到客户的机器上。
  • jq 里一切皆过滤器:select 保留符合条件的记录,@csv 把它们输出给电子表格。
  • 用 --arg 或 --argjson 从 shell 传值,不要自己拼接带引号的字符串。
四个 jq 步骤自上而下排列,用 | 符号和箭头相连。.items[] 拆出三笔订单:A1(C9,failed,1200)、A2(C3,paid,800)、A3(C9,failed,90)。select(.status=="failed") 去掉 A2,select(.amount>500) 去掉 A3,[.id,.cust_id,.amount] | @csv 最终只输出一行 "A1","C9",1200,以橙色高亮。
三笔示例订单依次经过各个 jq 过滤器:每经过一个 |,记录就少一些,直到剩下一行 CSV 回答客户的问题。图中为清晰起见把条件拆成两次 select;正文中的命令用 and 把两个条件合并进一个 select。来源:文中的 orders.json 示例,jq 1.8 手册。

客户会议开到半小时,运营团队问了一个很平常的问题:这周金额超过 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:

{"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 为真时原样返回输入,否则丢弃。

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

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

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

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

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

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

从 JSON 到客户打得开的文件

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

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 这对函数能在对象和键值对数组之间转换,因此不必重新列出所有字段就能重命名某个键:

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 的命令就是很好的起点:真实的问题,真实的数据,真实的数字。

这篇文章对你有帮助吗?

4 个信源
路线图上的下一篇 · 阶段 1: 基础认知Bruno 把 API 集合放进 Git,而不是云端客户禁止数据外发时,无账号、无云同步的 API 客户端能省掉安全团队的大量追问。