Python csv.DictWriter 缺少字段时如何设置 extrasaction

用 csv.DictWriter 写 CSV 时，很多人会把“字典缺少字段”和“字典多出字段”混为一谈。真正的处理方式是：行字典缺少 fieldnames 中的键，由 restval 补值；行字典出现不在 fieldnames 中的键，才由 extrasaction 决定。默认值是 'raise'，会抛出 ValueError；如果确认多出来的键可以丢弃，再设置 extrasaction='ignore'。

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

先判断：到底是缺少字段还是多了字段

fieldnames 是输出列的白名单和顺序。例如它是 ['name', 'email', 'role']，每一行都会按这个顺序写出三列。字典没有 role，属于缺少字段，使用 restval；字典多了 department，属于额外字段，使用 extrasaction。

先保留默认 raise，确认问题能被看见

下面的例子故意让第二行多出 department。默认策略不会默默改写数据，而是在 writerow() 处失败，这通常是排查导出字段漂移的最快信号。

import csv

fieldnames = ["name", "email", "role"]
rows = [
    {"name": "Lin", "email": "lin@example.com"},  # 缺少 role，由 restval 处理
    {"name": "Mia", "email": "mia@example.com", "role": "admin", "department": "ops"},  # 多出键
]

with open("users.csv", "w", newline="", encoding="utf-8") as csvfile:
    # 默认 extrasaction="raise"，先让额外字段暴露出来
    writer = csv.DictWriter(csvfile, fieldnames=fieldnames, restval="未填写")
    writer.writeheader()  # 写入固定表头，保证列顺序稳定
    for row in rows:
        writer.writerow(row)  # 第二行会因 department 抛出 ValueError

这里第一行的 role 会写成“未填写”，但循环在第二行停止。这个行为适合接口字段刚发生变化、你还不确定是否应该丢字段的阶段。

确认可以丢弃额外键时设置 extrasaction='ignore'

如果上游记录经常带有导出不需要的元数据，可以在构造器中显式设置：

import csv

fieldnames = ["name", "email", "role"]
row = {"name": "Mia", "email": "mia@example.com", "role": "admin", "department": "ops"}

with open("users.csv", "w", newline="", encoding="utf-8") as csvfile:
    # ignore 只忽略不在 fieldnames 中的键，不改变列顺序
    writer = csv.DictWriter(
        csvfile,
        fieldnames=fieldnames,
        restval="未填写",
        extrasaction="ignore",
    )
    writer.writeheader()  # 表头仍只包含三个声明列
    writer.writerow(row)  # department 被忽略，写入成功

生成内容应是：

name,email,role
Mia,mia@example.com,admin

注意，ignore 不会把额外键自动变成新列，也不会解决列名拼写错误。若 emali 是误拼写，忽略它可能让邮件地址悄悄丢失。

用 restval 处理真正缺少的字段

如果目标是让缺少的列拥有明确占位值，应继续使用 restval，不要误改 extrasaction：

import csv

fieldnames = ["name", "email", "role"]
row = {"name": "Lin", "email": "lin@example.com"}  # 没有 role

with open("users.csv", "w", newline="", encoding="utf-8") as csvfile:
    # restval 只填充缺少的 fieldnames 键
    writer = csv.DictWriter(csvfile, fieldnames=fieldnames, restval="未填写")
    writer.writeheader()
    writer.writerow(row)

输出第三列为“未填写”。写入后可以用 csv.DictReader 复读，检查表头是否为 name,email,role，并确认缺少值和额外键的处理都符合数据契约。

生产代码该选哪一种策略

导出财务、权限或对账数据时，我更倾向保留 raise，并记录导致失败的行，让字段变更尽早进入评审。只有在额外键属于已知元数据、且不会影响业务含义时，才使用 ignore。另一种更稳妥的做法是先计算额外键集合，记录日志后再把过滤后的字典交给写入器。

无论采用哪种策略，都要把 newline="" 和明确的 encoding="utf-8" 写在打开文件的位置；这样跨平台读取时更容易复查换行和中文内容。

常见问题

extrasaction 能填补缺少的列吗？

不能。缺少列由 restval 填充；extrasaction 只决定多余键是抛错还是忽略。

为什么设置了 ignore 仍然没有新列？

因为输出列由 fieldnames 决定。想输出新列，必须把列名加入 fieldnames，而不是依赖行字典自动扩展。

默认 raise 什么时候更好？

当额外字段可能代表拼写错误、接口升级或敏感数据误导出时，默认抛错更安全，也更容易定位数据问题。

把三个参数记成一句话即可：fieldnames 定列，restval 补缺，extrasaction 管多。先判断字段差异，再决定是暴露问题还是明确忽略。