Python dataclass 的列表默认值为什么要用 default_factory

给 dataclass 写列表字段时，推荐使用 field(default_factory=list)。原因不是语法更漂亮，而是列表属于可变对象：工厂函数会在每次实例需要默认值时新建一个列表，避免实例之间意外共享状态。当前 Python 的 dataclass 还会直接拒绝 items: list[str] = [] 这类可变默认值。

为什么列表默认值会变成共享状态

普通类里把列表放在类属性上，多个实例都可能沿着属性查找拿到同一个对象。dataclass 选择在声明阶段拦截这种写法，是为了让“每个订单都有自己的标签列表”成为明确规则，而不是靠开发者记住复制对象。

错误示例通常长这样：

from dataclasses import dataclass

@dataclass
class Task:
    # 不要把可变列表直接放在默认值位置
    labels: list[str] = []

在当前 Python 中，装饰 dataclass 时会抛出 ValueError，提示对可变默认值使用 default_factory。这个限制把隐蔽的状态污染变成了立即可见的定义错误。

default_factory 怎样把创建时机交给 dataclass

field(default_factory=list) 传入的是函数本身，而不是函数调用结果。dataclass 生成的 __init__ 在调用方省略 labels 时，才会调用这个零参数工厂。

from dataclasses import dataclass, field

@dataclass
class Task:
    name: str
    # 每个 Task 构造时都会得到新的空列表
    labels: list[str] = field(default_factory=list)

first = Task("整理日志")
second = Task("备份数据")
first.labels.append("urgent")

print(first.labels)   # ['urgent']
print(second.labels)  # []
print(first.labels is second.labels)  # False

这里的关键不是 list() 返回空列表，而是它在每次缺省构造时才执行。若调用 Task("导入", labels=["batch"])，调用方提供的列表会直接成为该实例的字段值。

什么时候使用内置工厂，什么时候自己写函数

空列表、空字典和空集合直接使用 list、dict、set 最清楚。如果默认容器需要初始内容，则写一个无参数函数，或使用不依赖实例字段的 lambda：

from dataclasses import dataclass, field

def default_headers() -> dict[str, str]:
    # 返回全新的字典，避免请求对象互相修改
    return {"Accept": "application/json"}

@dataclass
class RequestPlan:
    # 工厂必须可以在没有参数时调用
    headers: dict[str, str] = field(default_factory=default_headers)
    retries: list[int] = field(default_factory=lambda: [0, 1, 2])

不要写成 default_factory=default_headers()，那会在类定义阶段先执行函数，把字典结果当成工厂，随后失去“每个实例新建”的意义。工厂也不能直接依赖 self；如果默认值依赖其他字段，应在构造后用 __post_init__ 处理。

用一张清单检查可变字段设计

遇到“列表默认值为什么报错”或“两个对象为什么一起变化”，按下面顺序检查：

1. 字段默认值是否是列表、字典、集合等可变对象；是的话改成 field(default_factory=类型)。
2. 传入的是函数本身，还是已经执行后的结果；确认没有写成 default_factory=list()。
3. 工厂是否为零参数；需要配置时，把配置捕获在闭包或独立函数里，不要读取不存在的 self。
4. 是否把外部传入的列表继续暴露给调用方；若需要隔离输入对象，要在业务边界显式复制，而不是误以为 default_factory 会替你深拷贝。

继承 dataclass 时，默认字段仍参与生成的构造函数；若新增字段有默认值，注意不要让无默认字段排在它后面。序列化时，asdict() 会递归转换字段并复制嵌套对象，这属于序列化行为，和默认值工厂是两件事。

常见问题

default_factory 只能用于列表吗？

不是。它适合任何需要在实例构造时创建的默认对象，例如 dict、set 或自定义配置对象，只要工厂是零参数可调用对象。

显式传入列表后还会再调用工厂吗？

不会。工厂只负责补足缺省值；构造调用已经提供字段时，dataclass 使用传入对象。

用了 default_factory 就一定不会共享嵌套对象吗？

不一定。它只保证工厂返回的顶层对象按实例创建。若工厂内部复用了全局列表或嵌套可变对象，仍然可能共享，工厂应返回完整的新对象。

官方说明见 Python dataclasses 文档：default_factory 在需要默认值时调用，且不能与 default 同时指定。把它当成“实例级默认对象构造器”，就能自然地区分固定值、外部输入和需要隔离的容器。