# 自动合并报表前，先确认 CSV 输入规则

## 文档明确的机制

CSV 是电子表格和数据库常见的导入、导出格式，但 Python 文档也明确说明：在 RFC 4180 尝试标准化之前，CSV 已被使用多年；由于缺乏严格定义，不同应用生成和消费的数据常有细微差异。因此，自动合并报表不能只按“逗号分隔文件”这个名称判断输入，而要先确认分隔符、引号、换行、字段名和行列数量等规则。

`csv.reader(csvfile, dialect='excel', **fmtparams)` 会返回读取对象，从给定的 `csvfile` 处理行。`csvfile` 必须是字符串的可迭代对象，每个字符串应符合读取器定义的 CSV 格式；常见对象是文件类对象或列表。如果传入文件对象，文档要求使用 `newline=''` 打开。脚注说明，不指定 `newline=''` 时，引号字段内嵌换行可能无法正确解释；在使用 `\r\n` 行尾的平台上写入还可能多出 `\r`。

读取结果方面，`csv.reader` 每读出一行，就返回一个字符串列表。除非指定 `QUOTE_NONNUMERIC`，否则不会自动做数据类型转换；在该选项下，未加引号的字段会转换为浮点数。这意味着默认读入的金额、日期、编号仍是字符串，合并程序若要按数值或日期处理，需要自己明确转换规则，不能把 `csv.reader` 当作业务类型校验器。

格式差异可通过方言和格式化参数描述。文档列出的参数包括：`delimiter` 是分隔字段的单字符字符串，默认为逗号；`quotechar` 是用于引用包含特殊字符字段的单字符字符串，默认为双引号；`doublequote` 控制字段内 `quotechar` 如何处理，默认为 `True`；`skipinitialspace` 为 `True` 时，会忽略紧跟分隔符后的空格，默认为 `False`；`strict` 为 `True` 时，遇到错误 CSV 输入会抛出 `csv.Error`，默认为 `False`。读取器还提供只读的 `dialect` 属性和 `line_num` 属性。文档特别说明，`line_num` 是从源迭代器读取的行数，不等于返回的记录数，因为记录可能跨多行。

需要按字段名取值时，可使用 `csv.DictReader`。如果创建时不传 `fieldnames`，文件第一行的值会作为字段名，并且第一行不会出现在结果中；如果显式传入 `fieldnames`，这些字段名会被使用，第一行也会包含在结果中。字典会保留字段名的原始顺序。若某行字段多于字段名，剩余数据会放入列表，并用 `restkey` 指定的字段名保存，`restkey` 默认为 `None`；若非空行字段少于字段名，缺失值会填入 `restval`，其默认值也是 `None`。

文档还提供 `Sniffer`：`sniff(sample, delimiters=None)` 可分析样本并返回反映所发现参数的方言；`has_header(sample)` 可判断第一行是否像表头。但文档明确提醒，`has_header()` 是粗略启发式方法，可能产生误报和漏报。

## 团队自行约定的接手建议

以下是团队接手自动合并任务时可自行约定的检查清单，不是 Python `csv` 模块额外提供的能力。

第一，合并前固定输入契约。团队可要求每份报表说明编码、分隔符、引号字符、是否有表头、表头名称和字段顺序。若多个来源分别由 Excel、类 UNIX 程序或其他系统导出，不应仅凭文件后缀假设格式一致；可在读取时显式传入对应方言或格式化参数。

第二，明确 `DictReader` 的字段策略。若希望第一行作为表头，就不要传入 `fieldnames`；若团队要强制使用统一字段名，可显式传入 `fieldnames`，但此时文件第一行会被当作数据行处理，必须确认源文件是否仍包含表头。对接手人来说，还应检查多余字段是否进入 `restkey`、缺失字段是否落入 `restval`，避免静默改变报表宽度。

第三，把“能解析”和“业务正确”分开。`csv.reader` 能按 CSV 语法返回字符串列表，并不代表金额口径、部门名称、日期格式或重复记录正确。团队可在 CSV 解析之后增加自己的业务校验；这些校验规则需要由团队定义，不能声称来自 `csv` 模块。

第四，谨慎使用自动探测。`Sniffer` 可用于分析样本，但 `has_header()` 文档已说明是粗略启发式，且可能误报、漏报。团队若在无人值守的合并流程中使用它，应保留人工确认或固定白名单规则；不能把启发式判断当作确定的字段发现能力。

## 边界与总结

Python 文档展示的是 CSV 读写模块的机制：它可以隐藏不同 CSV 方言中的部分读写细节，支持序列形式的 `reader`/`writer`，也支持字典形式的 `DictReader`/`DictWriter`。但文档没有声称它会自动发现业务错误、校验财务口径或推断报表含义。

因此，自动合并报表前，最稳妥的做法是先确认文件打开方式、方言参数、表头与字段名，再决定如何处理多列、缺列、类型转换和异常记录。明确哪些结论来自 Python 文档，哪些只是团队内部约定，才能避免把“文件可读”误当成“报表可合并”。

## 立即实践

体验现有 [AI 工作流 ROI 诊断器](/demos/ai-workflow-roi-diagnostic/index.html)，验证上述工作流的输入、结果与下一步操作。此 Demo 是相关实践工具，不代表原项目的完整实现。


来源：[自动合并报表前，先确认 CSV 输入规则](https://docs.python.org/3/library/csv.html)