JSON 转 CSV

形状不匹配

JSON 是一棵树，CSV 是一个矩形，因此任何转换都必须决定如何处置树上放不进矩形的部分。唯一能干净映射的形状是「扁平对象组成的数组」：每个对象一行，每个键一列。除此之外的一切都需要额外的规则。

嵌套对象是容易的一类。{"role": {"team": "core"}} 会变成名为 role.team 的列，既保留了取值路径，也能被绝大多数电子表格导入向导识别。嵌套数组更棘手，因为展开它们会改变行数，并悄悄复制周围的数据。本工具把它们作为 JSON 文本保留在单个单元格里——牺牲了可查询性，但绝不会凭空造出源数据里没有的记录。

字段缺失与列顺序

真实世界的 JSON 很少整齐划一。这条记录有 nickname，下一条没有；某个字段只在某次迁移之后才出现。如果转换器只根据第一个对象确定列，其余字段就会被悄无声息地丢掉。

这里的列表是所有记录中全部键的并集，按首次出现的顺序排列。缺少某字段的记录会得到一个空单元格，而不是被跳过，因此行数始终与输入的记录数一致。选择首次出现顺序而非字母序，是为了保留作者原本的分组意图——id 和 name 会留在最前面，而不会被打散。

引号、分隔符与 Excel

RFC 4180 规定：字段若包含分隔符、双引号或换行，就必须加引号，而内嵌的双引号通过写两遍来转义。本工具对每个单元格（包括表头）都应用这条规则，因此 Grace, Jr. 这样的值或多行地址能够完整地通过任何合规解析器往返。

分隔符的选择比看上去重要。在以逗号作小数点的地区——欧洲大陆的大部分国家——Excel 期待的是分号，否则整行都会被塞进 A 列。BOM 选项会在文件开头加上 UTF-8 字节序标记，正是它告诉 Windows 版 Excel 按 UTF-8 而不是旧式代码页读取；没有它，非 ASCII 的名字会变成乱码。这两个选项都不在默认路径上，恰恰因为它们会让其他工具出问题——只在给 Excel 用时才打开。