Python csv.DictReader 缺失列时如何给出明确错误

导入 CSV 时，csv.DictReader 不会替你判断业务字段是否齐全：表头缺少 email，它仍然可以创建读取器；某一行少一个单元格，读取结果通常只是把对应值变成 None。可靠的做法是先检查 reader.fieldnames，再在遍历每行时检查必填值，并把文件名、行号和字段名放进错误信息。

先分清缺失列、缺失值和多余列

官方 csv 文档说明，DictReader 会把每行映射成字典，键来自 fieldnames；如果不显式传入，默认从文件第一行读取。行内字段不足时由 restval 补值，默认是 None；字段太多时可以用 restkey 接住多余字段。

因此，业务校验至少要分两层：reader.fieldnames 中没有必需字段，是“缺失列”；字段存在但某一行为空，是“缺失值”。额外列通常可以先保留，不要因为供应商多传了一个字段就误判为缺列。

把表头检查放在读取循环之前

检查表头时不要直接写 required - set(reader.fieldnames)，因为空文件的 fieldnames 可能是 None。同时使用 utf-8-sig 可以处理 Excel 导出的 UTF-8 BOM，避免第一列被读成带不可见字符的名称。

下面的函数把“结构错误”固定成一个明确的 ValueError。错误中同时列出实际字段，排查时不用再打开文件猜列名：

import csv
from pathlib import Path

REQUIRED_FIELDS = ("order_id", "email", "amount")

def read_orders(csv_path: str):
    path = Path(csv_path)
    # utf-8-sig 兼容常见表格软件写出的 UTF-8 BOM。
    with path.open("r", encoding="utf-8-sig", newline="") as stream:
        reader = csv.DictReader(stream)
        actual_fields = reader.fieldnames or []
        missing_fields = [
            field for field in REQUIRED_FIELDS if field not in actual_fields
        ]
        # 表头不完整时立即失败，不让错误拖到业务处理阶段。
        if missing_fields:
            found = ", ".join(actual_fields) or "无"
            missing = ", ".join(missing_fields)
            raise ValueError(
                f"{path.name}: 缺少列 [{missing}]；已发现列 [{found}]"
            )

        for line_number, row in enumerate(reader, start=2):
            # DictReader 对短行的默认补值是 None；空字符串也按缺失处理。
            empty_fields = [
                field for field in REQUIRED_FIELDS
                if row.get(field) in (None, "")
            ]
            if empty_fields:
                missing = ", ".join(empty_fields)
                raise ValueError(
                    f"{path.name} 第 {line_number} 行缺少值：{missing}"
                )
            yield row

为每一行补上行号和字段名

DictReader 的数据行从表头之后开始，所以示例用 enumerate(reader, start=2) 把 CSV 的物理行号带进错误。这里没有把 None 直接转换成字符串再保存，因为那会掩盖输入问题；导入边界应该尽早失败，并留下可搜索的字段名。

如果项目允许空值，应该把规则写成字段级配置，而不是删除整段检查。例如 amount 必须存在，但 remark 可以为空；这样“缺失值”与“合法空值”的边界才清楚。若还要检查数字格式，可以在通过非空检查后执行 Decimal(row["amount"])，并把转换异常包装成同样带行号的错误。

用一个小 CSV 导入器完成验收

可以用下面三种输入检查设计是否符合预期。完整表头且每行都有值时，生成器持续返回字典；缺少 email 列时，第一条数据被处理前就抛出“缺少列”；表头完整但第 8 行 email 为空时，错误会指向“第 8 行缺少值：email”。

• 表头：order_id,email,amount，行数据完整：允许继续导入。
• 表头：order_id,amount：报告缺少列 email。
• 第 8 行的 email 是空字符串或缺少单元格：报告行号和字段名。

这套边界也适合批量任务：捕获 ValueError 后记录文件名和错误文本，把原始 CSV 移到待修复目录，再重新导入。不要把 restval="" 当成校验方案；它只改变补值，不会知道某个字段在业务上是否必填。

常见问题

为什么不直接给 DictReader 传固定 fieldnames？

可以传，但这会改变第一行的处理方式，原始表头可能被当成数据行。若目标是校验供应商文件，先让 DictReader 读取真实表头，再检查字段通常更直观。

多余列是不是也应该报错？

不一定。向后兼容的导入器可以忽略或用 restkey 收集多余值；只有接口契约明确禁止扩展字段时，才把它升级为结构错误。

空文件怎么处理？

reader.fieldnames or [] 会把空文件转成空字段集合，最终报告全部必需列缺失。若产品要区分“空文件”和“缺列文件”，可以在缺失检查前单独抛出空文件错误。

核心原则很简单：表头问题在创建读取器后立刻检查，行数据问题在进入业务逻辑前定位；让错误包含文件名、行号和字段名，CSV 导入就从“看见 None”变成了可修复的输入契约。