Python csv.DictReader 遇到多余列怎么办：restkey、缺失列与行级校验

CSV 文件看起来只是“每行用逗号分隔”，但真实导入时经常会遇到某一行多出一列，或者末尾列缺失。Python 的 csv.DictReader 不会把这两种情况混成一个错误：多余字段默认放进 restkey 对应的列表，缺失字段则填成 None。掌握这个差异，才能在入库前准确拒绝异常行，而不是悄悄丢数据。

先固定表头，再用 restkey 捕获多余字段、用 None 判断缺失字段；行级校验通过后再转换类型和写入数据库。

DictReader 如何把一行映射成字典

假设导入文件的表头是 name,score,city。DictReader 先把表头绑定到字段位置，再逐行生成字典。正常行的三列一一对应；列数不一致时，它会沿着两条不同的数据路径继续处理。

import csv
from io import StringIO

csv_text = "name,score,city\nAlice,91,Shanghai\nBob,88\nChen,95,Shenzhen,extra"

reader = csv.DictReader(
    StringIO(csv_text),
    restkey="__extra__",
    restval=None,
)

for row in reader:
    print(row)

这段代码中，Bob 的 city 是 None，表示该位置根本没有值；Chen 的 __extra__ 是包含 extra 的列表。两者都不会自动抛异常，因此必须由业务校验决定是否接受。

用 restkey 和 None 把异常行拦在入库之前

实际项目中，建议把“解析”和“验收”分开。解析阶段只负责保留原始信息，验收阶段检查必填字段、额外字段和可转换类型。这样即使一行失败，也能把原始行号与具体原因写入错误报告。

import csv
from io import StringIO

REQUIRED = ("name", "score", "city")

def validate_rows(text: str) -> tuple[list[dict], list[dict]]:
    reader = csv.DictReader(
        StringIO(text),
        restkey="__extra__",
        restval=None,
    )
    accepted = []
    rejected = []

    for line_no, row in enumerate(reader, start=2):
        missing = [key for key in REQUIRED if row.get(key) is None]
        extra = row.get("__extra__") or []
        if missing or extra:
            rejected.append({
                "line": line_no,
                "missing": missing,
                "extra": extra,
            })
            continue
        try:
            row["score"] = int(row["score"])
        except (TypeError, ValueError):
            rejected.append({"line": line_no, "reason": "score 不是整数"})
            continue
        accepted.append(row)

    return accepted, rejected

这里的关键路径是 row.get("__extra__") 与 row.get(key) is None。前者识别多余列，后者只识别缺列；如果业务还禁止空值，需要另加 row[key] == "" 的检查。score 的转换放在结构校验之后，避免把格式问题和类型问题混在一条错误里。

三个容易误判的边界

还要留意表头本身。如果表头写错，逐行校验再严密也只能围绕错误字段名工作。导入前可以先检查 reader.fieldnames 是否与预期字段集合一致，并把文件编码、分隔符和引号规则固定在调用方。

相关问题：什么时候不该继续读入

多余字段一定要拒绝吗？

如果文件来自人工导出或上游版本经常增加列，建议先记录并按兼容策略处理；如果字段顺序代表金额、账号等高风险数据，则应直接拒绝，避免错位入库。

为什么不能只判断字典长度？

多余字段会被放入一个列表值，缺失字段仍可能出现在字典中，因此长度只能说明表面结构，不能替代对 None、空字符串和 __extra__ 的逐项检查。

如何让错误报告能定位原文件？

至少保存文件标识、数据行号、缺失字段、多余字段和原始文本摘要；不要只保存异常类型，否则修正文件时还要重新人工寻找问题行。

小结

DictReader 的宽松读取适合先保留数据、后做业务验收。用 restkey 显式接住多余字段，用 None 区分缺列，再把结构检查、类型转换和错误记录分成独立步骤，CSV 导入就能从“读到了”升级为“可验证地读对了”。