数据和电子表格 · CSV 清理器

在 CSV 和 JSON 之间转换：形状、类型和丢失的内容

2026年5月4日 · 工作原理

csv json 数据格式

CSV 是平面文本，JSON 是嵌套的类型化数据，因此它们之间的转换涉及决策。这篇文章解释了表格数据的常见 JSON 形状、如何推断类型以及什么不能在往返过程中幸存下来。

API 需要 JSON，导出是 CSV，并且每个数字都作为字符串到达 - 为什么两种格式在类型上不一致

电子表格导出可以显示 42，而无需说明这些字符是否表示计数、产品代码或标识符。 JSON 可以区分数字和字符串，但 CSV 源无法提供这种区别。因此，ToolAcre 选择保守的表示形式：每个单元格都变成 JSON 字符串，包括数字、真实的单词和空单元格。

该决定使 0012 等文本保持完整，并使 API 集成的转换可预测。这也意味着下游代码必须在进行算术之前将字段转换为自己的模式。将生成的文件视为已键入的文件只会将假设从转换器转移到不太可见的应用程序代码中。

该路由生成一个顶级数组，其中每个数据行都有一个对象。标题单元格成为对象键，并且从相同的列位置获取值。空白的第三个标头将变为column_3，而名为id 的第二个标头将变为id_2，而不是覆盖第一个id 字段。

干净、唯一的名称很有用，但转换器不会小写、音译或替换空格。它仅在计算密钥时修剪标头，然后在需要时发明位置名称或数字后缀。如果 API 需要 customer_email 而不是客户电子邮件，请在依赖输出协定之前故意重命名该列。

概述建议将数组的数组和面向列的对象作为可选目标。它们是合理的数据设计，但这个接口不提供它们。它的输出始终是由第一个 CSV 行键控的 JSON 平面记录数组，缩进两个空格以进行可读检查。

这种狭窄的选择消除了列名所在位置的歧义，并使每个记录的形状都相似。如果另一个消费者需要数组，请在该消费者的模式下转换下载的 JSON 。声称 ToolAcre 在多个布局中进行选择将描述配置或面板代码中不存在的控件和分支。

不会发生类型猜测。 CSV 文本 42 变为“42”， false 变为“false”，空白变为“”而不是 null。这在工具记录和实现中是明确的，它将单元格直接映射到字符串属性。该路由不会检查列并决定所有非空值都是数字。

保留字符串也将本文与电子表格应用程序更改前导零、日期和长标识符的已发表讨论区分开来。这里的重点是转换器的实际契约：它避免了此类强制。消费者仍然负责解析已知数量并保持标识符不变。

在相反的方向上，ToolAcre 接受一个顶级 JSON 数组，其项目是对象。它按照第一次看到的顺序，根据每个对象的键的并集构建列，因此后面的记录引入的字段不会丢失。缺失、空和未定义的属性将变为空 CSV 单元格。

存储在属性内的对象或数组在该单元格内序列化为 JSON 文本。这保留了文本表示，但不会将嵌套结构转换为附加的列或行。非数组根和包含原始值的数组将被拒绝，因为两者都不匹配此路由支持的表模型。

考虑名称、活动、计数，然后是 Ada、true、007。 JSON 结果是一个数组，其中包含名为“Ada”、活动“true”和计数“007”的对象。将该平面对象数组转换回来会产生相同的三个文本单元格，因为没有类型推断删除零或转换布尔值单词。

现在在另一个值之前添加一个空白标题。 JSON 键变为column_4，因此即使源名称丢失，数据仍然可访问。然而，在标题宽度之外添加一个额外的单元格，加载器会警告有关参差不齐的行；该剩余单元格没有密钥并且不存在于 JSON 中。

该路由不是模式验证器、递归扁平化器或流 JSON 处理器。它接受一种记录的形状并报告无效的 JSON 或具有特定错误的不受支持的根。深度嵌套的记录需要围绕其域设计的映射，而不是自动承诺键中的标点符号会创建结构。

输入文件检查允许文件达到配置的 50 MB，并且 CSV 解析发生在工作线程中。这些事实并不能建立流：文件文本和完成的行仍然会具体化以进行转换。对于非常大的 JSON 工作流程，请使用其实现显式记录增量解析的系统，而不是在此处推断它。

转换是一组可见的选择：第一行作为键，平面对象作为记录，字符串作为值。 ToolAcre 使这些选择变得稳定，而不是根据样本进行猜测。空白和重复的标题接收确定性密钥，而参差不齐的输入在未命名的剩余值可能不被注意地消失之前出现。

使用预览确认分隔符和行形状，解决警告，然后下载或复制 JSON。生成的文件适合了解其自身架构的代码。它有意不替代该模式，并且它的限制是在格式更改期间保护文本 ID 的原因。