Python dataclass 的列表字段怎么写：default_factory 避开共享数据和初始化报错

给订单筛选条件加一个标签列表，本来只是一行字段定义：tags: list[str] = []。保存后服务甚至还没启动，解释器就报出 ValueError，提示可变默认值不能直接使用。第一次看到这个报错很容易觉得 dataclass 太严格；其实它是在提前挡住一个更难发现的问题——两个实例不该共用同一个列表。

实验一：先看 dataclass 为什么不接受空列表

先建一个最小文件 filters.py。它模拟接口层把筛选条件收进一个对象的场景：订单号是必填条件，标签是可选条件。下面的写法不要留在正式代码里，它的价值只是让报错出现得足够直接。

from dataclasses import dataclass


@dataclass
class OrderFilter:
    order_id: int
    tags: list[str] = []

运行这个文件，当前 Python 的 dataclass 会因为 [] 是不可哈希的默认值而抛出 ValueError。官方文档说明，这个判断是为了近似识别可变默认值。它并不是说所有不可哈希对象都有问题，而是在常见的 list、dict、set 场景里提前阻止共享状态悄悄混进构造函数。

这里别急着用 None 把报错压下去。先理解它防的是什么：普通类若把列表放在类属性上，两个实例会看见同一份列表。一个请求把标签追加进去，另一个请求读到的条件就会被污染；这种问题在单元测试里不一定立刻暴露，批量任务或长生命周期服务更容易踩到。

实验二：用 default_factory 在实例创建时生成列表

修复不复杂，关键是把“列表对象”换成“创建列表的函数”。field(default_factory=list) 表示构造每个 OrderFilter 时都调用一次无参的 list，而不是把某个已经存在的列表交给所有实例。

from dataclasses import dataclass, field


@dataclass
class OrderFilter:
    order_id: int
    tags: list[str] = field(default_factory=list)


first = OrderFilter(order_id=101)
second = OrderFilter(order_id=102)
first.tags.append("refund")

print(first.tags)              # ['refund']
print(second.tags)             # []
print(first.tags is second.tags)  # False

检查点很朴素：第一条筛选条件加入 refund 后，第二条仍是空列表，并且最后一行打印 False。如果这里得到的结果相反，说明代码某处仍然在复用外部容器，继续往构造参数、类属性或模块级常量里找。

一个容易写错的细节是括号。default_factory=list 传入的是函数本身；default_factory=list() 则是在类定义时先创建了列表，既不符合工厂的约定，也达不到每次初始化新建对象的目的。官方文档也规定，default 与 default_factory 不能同时设置。

实验三：字典、集合和配置对象怎么处理

同样的规则适用于字典与集合。字段默认值只要是“每个实例都应拥有自己一份”的可变对象，就应该通过工厂创建。最常见的三种写法可以放在一个请求模型里：

from dataclasses import dataclass, field


@dataclass
class ExportJob:
    columns: list[str] = field(default_factory=list)
    options: dict[str, str] = field(default_factory=dict)
    regions: set[str] = field(default_factory=set)


job = ExportJob()
job.options["format"] = "csv"
print(job.options)

如果默认值来自一份基础配置，不要直接把基础字典交给字段。可以用无参 lambda 在创建实例时做一次浅拷贝；但基础配置里有嵌套列表或嵌套字典时，浅拷贝只会复制最外层，需要重新设计不可变配置，或明确做深拷贝。工厂解决的是“何时创建”，不是自动替你决定“复制到多深”。

BASE_OPTIONS = {"format": "csv", "timezone": "UTC"}


@dataclass
class ReportJob:
    options: dict[str, str] = field(
        default_factory=lambda: dict(BASE_OPTIONS)
    )

空列表和 None 要按业务语义分开

default_factory=list 表示“默认就是没有元素的列表”。有些接口需要表达的却是“调用方根本没有传这个字段”，这时 None 更合适。比如批处理规则为空列表可以代表明确不启用任何规则，而 None 可以代表仍然沿用系统默认规则；两者在保存、合并配置和接口响应中都可能不同。

from dataclasses import dataclass


@dataclass
class BatchRequest:
    rules: list[str] | None = None


request = BatchRequest()
if request.rules is None:
    rules_to_use = ["daily"]
else:
    rules_to_use = request.rules

print(rules_to_use)

这段代码没有把 None 当成偷懒的替代品，而是把默认规则的决定位置写出来。字段一旦进入数据库、消息队列或 JSON 序列化边界，这种区分会显著减少“空数组到底是不是没传”的沟通成本。

提交前跑一组隔离检查

dataclass 给出的 ValueError 是一个很有价值的早期提醒，但真正的修复仍是明确每个字段的归属：它属于类、属于实例，还是属于一次请求。把这个判断做在模型定义阶段，后面的缓存、序列化和并发处理都会轻松很多。

相关问题

default_factory 可以写成任意函数吗？

可以，但它必须是无参可调用对象，并在需要默认值时返回新对象。除了 list、dict、set，也可用于创建日期、配置对象或自定义容器。

为什么不直接用 None，再在 __post_init__ 里补空列表？

这样做可行，但会让空列表和未提供值的语义混在一起。默认就需要独立空容器时，default_factory 更短也更直观；需要区分未提供时，None 才更合适。

冻结 dataclass 还需要 default_factory 吗？

需要。frozen 约束的是字段重新赋值，不会让嵌套的列表或字典自动变成不可变对象。只要字段默认值是可变对象，仍应为每个实例单独创建。