本文详解如何利用 jq 命令行工具，从嵌套 JSON 中精准提取 .Columns[].Id 作为 CSV 表头，并将 .Rows[].Values 映射为对应数据行，生成标准 CSV 输出，无需编程即可完成结构化转换。
本文详解如何利用 jq 命令行工具，从嵌套 json 中精准提取 `.columns[].id` 作为 csv 表头，并将 `.rows[].values` 映射为对应数据行，生成标准 csv 输出，无需编程即可完成结构化转换。
在数据处理和 ETL 场景中，常需将 API 返回的嵌套 JSON（如报表、查询结果）快速转为可导入 Excel 或数据库的 CSV 格式。当 JSON 具有明确的元数据结构（如 Columns 定义字段名、Rows 存储值数组）时，jq 是最轻量、高效且无需依赖环境的解决方案。
以如下典型 JSON 为例：
{
"Columns": [
{"Id": "ItemName", "IsEditable": false},
{"Id": "Date", "IsEditable": false},
{"Id": "Qty", "IsEditable": false}
],
"Rows": [
{"Values": ["ITEM1", "10-MAY-2024", "100"]},
{"Values": ["ITEM2", "20-MAY-2024", "200"]},
{"Values": ["ITEM3", "30-MAY-2024", "400"]}
]
}目标是生成标准 CSV（含表头），且仅保留 Columns[].Id 和 Rows[].Values，忽略其余字段（如 QueryHandle, RowCount 等）。
✅ 正确的 jq 转换命令
jq -r '[.Columns[].Id], (.Rows[].Values) | @csv' input.json
输出结果：
"ItemName","Date","Qty" "ITEM1","10-MAY-2024","100" "ITEM2","20-MAY-2024","200" "ITEM3","30-MAY-2024","400"
? 命令解析：
- [.Columns[].Id]：提取所有列 ID，构造成一个字符串数组 ["ItemName","Date","Qty"]；
- .Rows[].Values：遍历每行，提取 Values 数组（如 ["ITEM1","10-MAY-2024","100"]）；
- ,（逗号）：将表头数组与所有行数组按顺序拼接为流式输入（即先输出表头，再逐行输出数据）；
- @csv：jq 内置格式化器，自动处理字段转义（如含逗号、引号、换行的值会加双引号）、UTF-8 编码兼容，并使用英文逗号分隔；
- -r（raw output）：禁用 JSON 字符串外层引号，直接输出纯文本 CSV。
⚠️ 注意：切勿写成 .Columns[].Id, .Rows[].Values | @csv —— 这会把每个 Id 单独作为一行（3 行表头），再叠加数据行，导致 CSV 结构错乱。
?️ 进阶技巧（按需选用）
| 需求 | jq 片段 | 说明 |
|---|---|---|
| 首字母大写表头（如 "itemname" → "Itemname"） | (.Columns[].Id | sub("^(.)"; .[0:] |= ascii_upcase)) | 需结合 map() 使用，较复杂，建议后处理或用 Python |
| 去除双引号包裹（无转义需求时） | @csv | gsub("^\"|\"$"; "") | 不推荐：破坏 CSV 规范，遇含逗号字段将解析失败 |
| 导出到文件 | jq -r '[.Columns[].Id], (.Rows[].Values) | @csv' data.json > output.csv | 直接重定向，生成标准 CSV 文件 |
| 跳过空行或无效 Rows | (.Rows[]? | select(.Values)) | 增强健壮性，过滤缺失 Values 的行 |
? 替代方案：Python（适合复杂逻辑或集成脚本）
若需大小写转换、日期标准化、类型推断或批量处理，Python + pandas 更灵活：
import json
import csv
import sys
with open(sys.argv[1]) as f:
data = json.load(f)
headers = [col["Id"] for col in data["Columns"]]
rows = [row["Values"] for row in data["Rows"]]
with open("output.csv", "w", newline="", encoding="utf-8") as f:
writer = csv.writer(f, quoting=csv.QUOTE_MINIMAL)
writer.writerow(headers)
writer.writerows(rows)运行：python json_to_csv.py input.json
✅ 总结
- 首选 jq：对结构清晰的 JSON→CSV，单条命令、零依赖、秒级完成，符合 Unix 哲学；
- 核心要点：用数组字面量 [...] 构建表头，用逗号 , 拼接流式数据，严格依赖 @csv 保证格式安全；
- 避坑提醒：避免直接展开 .Columns[].Id（会破坏表头完整性），勿省略 -r 参数；
- 扩展建议：生产环境可封装为 shell 函数或 Makefile target，提升复用性。
掌握该模式后，90% 的报表类 JSON 导出需求均可一行解决。
