Python csv.DictWriter怎样处理额外字段和缺失字段

我在做一段 CSV 导出时，最容易忽略的不是文件打开方式，而是“字典里的键和表头不完全一致”这件事。记录少一个键时，导出不能临时改变列结构；记录多一个键时，也不能悄悄把业务字段写到表格末尾。

csv.DictWriter 的处理规则其实很明确：fieldnames 决定列集合和顺序，restval 为缺失键提供默认值，extrasaction 决定额外键是抛出 ValueError 还是忽略。把这三个参数分清楚，CSV 导出的边界就稳定了。

官方地址：https://docs.python.org/3/library/csv.html

一、先把输出 schema 固定下来

先把导出文件当成一个小型 schema，而不是把每条字典直接“倾倒”进去。下面的 fieldnames 同时完成两件事：规定表头顺序，也规定每条记录允许被写出的键。

import csv

# fieldnames 是 CSV 的固定列集合，也决定每行的输出顺序。
fieldnames = ["name", "email", "department", "enabled"]
records = [
    {"name": "林默", "email": "lin@example.com", "department": "研发", "enabled": True},
    {"name": "周宁", "email": "zhou@example.com", "department": "测试", "enabled": False},
]

# newline='' 交给 csv 模块处理换行，避免不同平台出现空白行。
with open("members.csv", "w", newline="", encoding="utf-8") as output:
    writer = csv.DictWriter(output, fieldnames=fieldnames)
    writer.writeheader()
    writer.writerows(records)

这里没有依赖字典本身的插入顺序。即使上游对象把 email 放到了最后，输出仍然会按 name,email,department,enabled 排列。对于后续要被 Excel、脚本或数据库读取的文件，这个稳定性比“当前样例恰好能写出”更重要。

二、缺失字段用 restval 补齐

如果字典缺少某个 fieldnames 中的键，DictWriter 会写入 restval。它的默认值是空字符串，适合“缺失就留空”的场景；如果报表需要明确标记，也可以传入 "未填写" 或其他业务默认值。

import csv

fieldnames = ["name", "email", "department"]
records = [
    {"name": "林默", "email": "lin@example.com"},
    {"name": "周宁", "department": "测试"},
]

with open("members-with-default.csv", "w", newline="", encoding="utf-8") as output:
    # 缺少 email 或 department 时写入这个值，不改变列数。
    writer = csv.DictWriter(
        output,
        fieldnames=fieldnames,
        restval="未填写",
    )
    writer.writeheader()
    writer.writerows(records)

最终表格仍然有三列：第二行的 department 会得到“未填写”，第三行的 email 会得到“未填写”。要注意，显式写入 None 和“字典里没有这个键”不是同一回事：前者是已有值，后者才由 restval 接管。

三、额外字段用 extrasaction 选择严格或兼容

额外字段是指字典里出现了不在 fieldnames 中的键。默认的 extrasaction="raise" 会抛出 ValueError，这适合把上游 schema 漂移尽早暴露出来；如果导出只关心固定报表列，则可以使用 extrasaction="ignore"。

import csv

fieldnames = ["name", "email"]
record = {
    "name": "林默",
    "email": "lin@example.com",
    "department": "研发",  # 这是额外字段，不在导出 schema 中。
}

with open("strict.csv", "w", newline="", encoding="utf-8") as output:
    strict_writer = csv.DictWriter(output, fieldnames=fieldnames)
    strict_writer.writeheader()
    try:
        # 默认 extrasaction='raise'，发现未声明字段就停止当前写入。
        strict_writer.writerow(record)
    except ValueError as exc:
        # 这里可以记录来源或转成业务错误，避免静默丢列。
        print(f"记录字段不匹配：{exc}")

with open("compatible.csv", "w", newline="", encoding="utf-8") as output:
    compatible_writer = csv.DictWriter(
        output,
        fieldnames=fieldnames,
        extrasaction="ignore",
    )
    compatible_writer.writeheader()
    # 只输出 name 和 email，department 会被明确忽略。
    compatible_writer.writerow(record)

我通常在内部数据管道选择严格模式，在面向多来源数据的固定报表选择忽略模式。但“忽略”应该是有意的产品决定，而不是为了让任务暂时通过而随手添加。否则字段拼写错误也会被当成正常导出。

四、批量写入前先做记录规范化

如果数据来源很多，可以在调用 writerow 之前做一层规范化。这样额外字段是否丢弃、缺失字段填什么，都集中在一个函数里；写入器只负责把已经符合 schema 的记录转换成 CSV。

import csv

FIELDNAMES = ["name", "email", "department"]

def normalize_record(source: dict[str, object]) -> dict[str, object]:
    # 只保留声明字段，避免导出行为依赖上游字典的多余键。
    normalized = {key: source.get(key, "未填写") for key in FIELDNAMES}
    # 显式保留空值语义：已有 None 不等同于缺失键。
    return normalized

records = [
    {"name": "林默", "email": "lin@example.com", "department": "研发", "debug": True},
    {"name": "周宁", "email": "zhou@example.com"},
]

with open("normalized.csv", "w", newline="", encoding="utf-8") as output:
    writer = csv.DictWriter(
        output,
        fieldnames=FIELDNAMES,
        # 规范化后理论上没有额外键，这里仍保留严格模式作为保险。
        extrasaction="raise",
    )
    writer.writeheader()
    writer.writerows(normalize_record(record) for record in records)

这段做法的基线很简单：无论输入记录多出多少业务字段，最终都只产生固定的三列；缺少字段会得到统一默认值。后续如果要改列名或默认策略，只需要改 schema 和规范化函数，不必在每个导出调用点加分支。

五、用边界样例观察真正的 CSV 结果

写完策略后，建议至少准备三类小样例：完整记录、缺少字段的记录、包含额外字段的记录。这里的观察目标不是追求复杂测试，而是确认你选择的策略和产品需求一致。

另一个容易混淆的点是打开文件时的 newline=""。Python 官方文档建议读写 CSV 文件时使用它，让 csv 模块自己处理换行；这和 restval、extrasaction 是不同层次的问题，不能用其中一个替代另一个。

总结：把“字段不一致”变成显式策略

DictWriter 的核心不是自动猜测字段，而是让你明确声明输出契约。先用 fieldnames 固定列顺序，再用 restval 处理缺失键；遇到额外键时，内部管道优先考虑默认的 raise，固定报表才考虑 ignore。当输入来自多个系统时，再把这些规则收口到写入前的规范化函数中。

相关问题

• DictWriter 为什么会报 ValueError？通常是输入字典包含不在 fieldnames 中的额外键，默认 extrasaction 为 raise。
• 缺失字段怎样写成空字符串？不传 restval 就会使用默认空字符串，也可以显式设置 restval=""。
• 能不能让额外字段自动追加成新列？不能依赖 DictWriter 自动扩展；应先重新计算 schema，再创建新的 fieldnames。
• writerow 和 writerows 有什么区别？前者写一条字典记录，后者接收可迭代的多条记录，字段规则相同。