数据格式与结构化数据

把 JSON 转为 CSV 表格查看

使用工具

生成文件容易让人以为只换格式，但表与树、文本与数值、值与注释携带的信息不同。无错误不保证意义全保留，选目标格式前先确定必须保留什么。

先做小型 JSON/CSV 往返，再看 YAML 注释和 TOML 的 null 缺失。完整业务数据转换前，用包含前导零、空字符串、缺字段、嵌套的几条记录明确规则。

转 CSV 的 JSON 输入

[{"id":"001","quantity":2,"active":true}]

CSV 产生 id、quantity、active 列，转回 JSON 时单元格都是字符串。001 保住了，2 和 true 也成字符串。工具不按外观猜类型，因此往返不保留原 JSON 类型。

转回后的值

[{"id":"001","quantity":"2","active":"true"}]

若自动转换所有像数值的单元格，001 又可能变 1。恢复类型需要与接收方约定列规则，如 id 文本、quantity 整数、active 用指定真伪表示。不能指望 CSV 独自恢复原类型。

三种无值状态

[
  {"id":"a","note":null},
  {"id":"b","note":""},
  {"id":"c"}
]

CSV 中 note 都变空白，转回无法判断原来是 null、空字符串还是缺失。保留区别需明确约定，如另设状态列。把空白都改 null 会改变另两种含义。

更新接口可能把缺字段当不修改、null 当清空，若如此，丢掉区别很重要。先查实际导入或 API 规则，再决定哪些字段可走 CSV，不把语义决定交给按钮。

嵌套输入

[{"id":"a","profile":{"city":"Tokyo"}}]

拒绝嵌套模式会拒绝转换；字符串化把 profile 作为 JSON 文本放一格，展开则生成 profile.city 列。两者都是表格表示，不是表原生保留嵌套类型。

反向转换不会把 JSON 样式单元格再解析为对象，也不会从 profile.city 自动重建 profile。原键本就含点时也需约定。应按接收方预期选择，不凭外观以为可逆。

用引号保护的 CSV 单元格

id,note
001,"red, blue"
002,"first line
second line"

此 CSV 除表头外有两条记录。按逗号或换行盲拆会把 note 内容拆成额外行列。用表预览确认 red, blue 一格、两行 note 也一格。物理行数不等于记录数。

表格公式防护会给相关单元格加前导撇号，改变文字。需区分展示保护与无损交换，并告知接收方是否启用，避免把前缀当原数据导入。

带说明的 YAML

# Retry only temporary failures
retries: 3
enabled: true

JSON 保留 retries、enabled，不保留注释。仅因值可转换就往返配置，可能丢失运维理由和注意事项。注释重要时，应保留原 YAML 或另设文档策略。

TOML 没有直接对应 JSON null 的值，所以工具拒绝含 null 的 JSON。改空字符串或删字段也许可输出，但会改含义，不应只为成功而自动替换。

大整数和日期也依赖目标类型与实现范围。当前 JSON→TOML 拒绝超出精确范围的整数。类型日期变 JSON 文本时，要确认时间与时区含义仍清楚，格式名称不保证完全可逆。

最后结构比较原 JSON 与返回 JSON，关注类型、null、缺失、嵌套而非键顺序。不同不必然失败，允许的转换可记录为规范；不可接受的损失则换格式或补元数据。

同时记录列选择、嵌套模式、公式保护和编码。应说明保留与改变了什么，而非声称来自 JSON 所以相同。转换只是交接一步，接收方仍需按预期理解。

接收方把 CSV 空栏当不修改，发送方却想删除值，即使无乱码或语法错也会不一致。压成表格前应约定空字符串、null、未指定的区别。加状态列或选其他格式属于交接设计，生成有效文件与共享同一含义需要分别验证。