什么是CSV？格式、规则、用途和常见陷阱

无抓取的抓取API可以以CSV格式返回结构化的网络数据，以用于电子表格、数据库导入和分析工作流。

什么是CSV文件？

CSV代表逗号分隔值。CSV文件将表格数据表示为文本：行表示记录，分隔符将每条记录划分为字段。第一行通常包含列名，尽管标题是可选的。文件扩展名通常是 .csv，注册的媒体类型是 text/csv.

这种熟悉的格式故意简单。客户导出可能包含标识符、名称、国家和账户状态的列。数据库可以将查询结果写入CSV，电子表格可以打开该文件，另一个系统可以导入相同的行，而无需共享专有的工作簿格式。

RFC 4180 文档记录了通用 CSV 格式和 text/csv 媒体类型它描述了逗号分隔符、CRLF 记录边界、可选头部和双引号转义。该文档是信息性的，而不是适用于每个名为 CSV 的文件的普遍法律。许多工具接受或生成变体，因此交换 CSV 文件仍然需要对其方言达成一致。

CSV语法是如何工作的

一个最小的CSV文件可以包含一个标题和三个记录：

id,name,country,active
101,Ada,GB,true
102,Lin,SG,false
103,Sam,CA,true

该示例中的每一行都有四个字段。标题提供标签，但不声明类型。读者可以推断出 id 是一个整数，并且 active 是布尔值，而另一个读取者可能将每个字段都保留为文本。除非数据协议指定其中一种，两者的解释都是可能的。

分隔符

逗号是标准分隔符，但分号、制表符和管道在区域导出和特定应用程序的数据流中很常见。十进制逗号地区通常使用分号以避免歧义。制表符分隔的值通常被称为TSV，但许多导入对话框将CSV和TSV归入一个“分隔文本”工作流程中。

生产者应该说明分隔符。从第一行猜测可能会失败，当值包含标点符号或当单列文件根本没有分隔符时。接收管道应允许显式的方言配置并报告检测到的设置。

引用和转义

根据RFC 4180的通用规则，包含逗号、双引号或记录边界的字段需要加引号。在引用字段内，双引号会被加倍：

id,name,note
201,"Rivera, Ana","Asked for ""priority"" handling"
202,Chen,"First line
Second line"

第二个记录显示，引用字段可能包含换行符。在应用CSV规则之前将文件拆分为行的解析器会损坏该记录。使用一个理解引用的CSV解析器，而不是通用字符串拆分。

规则 1. 仅输出翻译后的文本——不需要解释，没有额外的包裹代码围栏。 2. 精确保留Markdown/HTML结构（标题、列表、链接、表格）。 3. 保持任何占位符标记如@@CODEBLOCK_0@@或@@INLINECODE_0@@完全不变；绝不翻译、重排、合并或重新格式化它们。 4. 不要添加或删除```代码围栏，也不要将普通文本包装在代码块中。

一个标题行可以提高可读性，并让用户通过名称而不是位置来映射列。然而，CSV 语法无法证明标题的存在。接收系统需要配置或 header 媒体类型参数。列名应该是唯一、稳定且有文档记录的。未经合同修剪或转换大小写的标题可能会合并不同的字段。

CSV不定义的内容

CSV 描述字段边界，而不是领域含义。它没有提供一种通用的方法来声明数据类型、主键、关系、单位、时区、字符编码，或空字段是否表示空字符串、未知值或缺失值。

规则： 1. 仅输出翻译后的文本 — 不需要解释，不需要额外的包装代码块。 2. 精确保留Markdown/HTML结构（标题、列表、链接、表格）。 3. 任何占位符令牌如@@CODEBLOCK_0@@或@@INLINECODE_0@@保持完全不变；绝不翻译、重排序、合并或重新格式化它们。 4. 不要添加或删除```代码块，且不要将正常文本包装在代码块中。 The W3C 网络上表格数据和元数据模型 通过描述如何将表格文件与有关列、数据类型、标题和关系的元数据配对来解决这个空白。团队不必采用完整的模型，但应该在某个持久的地方提供等效的信息。

常见的CSV方言差异

为什么CSV仍然实用

CSV获得广泛支持。电子表格应用程序、数据库、命令行工具、数据框、分析平台和业务系统都可以读取或写入分隔文本。这种兼容性使得CSV成为一种可靠的扁平表格交接格式。

CSV也是可检查的。开发人员可以在文本编辑器中打开一个小文件，数据分析师可以在不安装特定领域查看器的情况下将其加载到电子表格中。由于表示具有较小的结构开销，它在宽且规则的表格中可以紧凑，尤其是在压缩后。

该格式在每个记录遵循一个模式时适用于仅追加的导出和批量导入。当一个记录包含嵌套对象、数组或一个可变字段集时，它不太适合。那些结构必须被扁平化为列，拆分为相关文件，或使用另一种约定编码到一个单元格中。

典型的CSV用例

CSV安全风险

CSV文件是数据，但电子表格软件可能将以等号等字符开头的单元格解释为公式。如果不可信的值变成公式，打开导出可能会触发那个电子表格环境支持的动作。这种问题通常被称为CSV或公式注入。

OWASP的CSV注入指导 解释了为什么输出不可信输入的应用程序必须考虑电子表格解释。生产者应该遵循目标电子表格当前的安全导出指导，并且不应假设引号字段可以消除公式语义。接收者应该在受控环境中打开未知文件，并在启用活动内容之前检查可疑的前导字符。

CSV摄取也需要资源控制。设置文件大小、行大小、列数和字段长度限制。拒绝格式错误的引号并提供明确的位置。保留原始文件以供审计使用，避免以改变字段到错误列的方式悄悄修复损坏的记录。

如何可靠地导入CSV

1. 保留原始字节。 保持源文件不变，以便可以重现编码、引号和行边界问题。
2. 设置或检测方言。 优先使用生产者提供的设置。如果需要检测，请记录结果并允许在加载高价值数据之前进行审查。
3. 显式解码。 UTF-8是一个合理的交换默认值，但字节顺序标记或合同元数据可能指示使用另一种编码。
4. 使用CSV库解析。 不要在逗号或换行符上拆分，因为引用的字段可能包含两者。
5. 首先验证形状。 在类型转换之前检查标题、重复列名、字段计数、必需列和最大大小。
6. 在架构下转换类型。 使用明确的区域和精度规则解析日期、小数、布尔值和标识符。
7. 隔离无效记录。 报告记录和原因，而不让一个格式错误的行影响其余数据集。

CSV与其他格式的比较

CSV最好被理解为一种扁平表的交换格式。JSON增加了嵌套对象、数组、布尔值、数字和null。NDJSON为流和日志保持每行一个独立的JSON值。Parquet以用于分析扫描的二进制布局存储类型列。XLSX工作簿可以保留公式、样式、工作表和更丰富的电子表格行为。

一个实用的管道可能在不同的边界使用几种格式。CSV可以是人工交接，JSON可以是API响应，Parquet可以是分析存储层。当转换与下一个消费者匹配时是有价值的；它不应该抹掉标识符、null语义、精度或来源。

如何创建干净的CSV文件

从稳定的列合同开始。使用唯一的标题，在每个记录中发出相同数量的字段，根据所选方言引用字段，并写一个声明的编码。当前导零很重要时，保持标识符字段为文本。使用双方都同意的明确日期表示，并为时间戳包含时区信息。

除非合同明确说明单元格包含JSON并定义其转义，否则不要将嵌套JSON放入单元格中。对于一对多关系，将相关记录分离到共享键的另一个文件中，或选择支持嵌套的格式。当交付包含多个文件、架构、校验和或分区时，添加清单。

结论

CSV成功是因为它为扁平表提供了一种小型、广泛支持的文本表示。它的明显简单性可能掩盖关于分隔符、引号、标题、编码、null、类型和电子表格行为的重要选择。可靠的CSV工作流将文档化的方言与数据架构配对，使用专用库进行解析，在转换前进行验证，并保留原始输入。通过这些控制，CSV仍然是网页数据、数据库、分析工具和业务用户之间的实用桥梁。