Python dataclass 默认值完整工作流：从可变默认值到 default_factory

Python 里的 dataclass 很适合写配置对象、任务参数、接口返回结构。它能少写很多样板代码，但默认值这一块如果处理得不稳，很容易把多个实例之间的数据搞混。

这篇文章按完整工作流来整理：什么时候可以直接写默认值，什么时候必须用 field(default_factory=...)，如何给 list、dict、set 这类字段建模，最后用一个小测试确认每个实例都有自己的独立对象。

摘要

dataclass 默认值的核心规则很简单：不可变值可以直接写，可变值不要直接放在字段定义上。对于列表、字典、集合这类字段，使用 field(default_factory=list)、field(default_factory=dict) 或自定义函数，让每次创建实例时都生成新的对象。这样可以避免实例之间共享同一份可变数据。

适合人群

• 用 Python 写配置类、请求参数类、任务对象、数据传输对象的开发者。
• 遇到列表或字典字段在多个对象之间互相影响的读者。
• 想把 dataclass 默认值规则整理成团队代码规范的人。

目标和边界：这篇文章解决什么问题

我们先把边界定清楚。本文解决的是 dataclass 字段默认值怎么写更稳，尤其是 list、dict、set 这类可变字段。它不展开讲 dataclass 的全部参数，也不讨论 ORM、Pydantic 这类更完整的数据建模框架。

最终要得到的是一个可复用判断流程：

• 字段默认值是数字、字符串、布尔值、None：通常可以直接写。
• 字段默认值是列表、字典、集合或自定义对象：优先使用 default_factory。
• 字段默认值需要运行一段初始化逻辑：写一个专门的工厂函数。
• 写完后创建两个实例，确认它们的可变字段不是同一个对象。

全流程总览：从可变默认值到 default_factory

先看整体路径。很多默认值问题不是语法不会写，而是没有在建模阶段区分“值本身能不能被修改”。列表、字典、集合都能被原地修改，所以它们不能当作普通常量看待。

这张图要表达的核心是：如果多个实例拿到同一个列表，一个实例追加数据，另一个实例也会看到变化。正确做法是让 dataclass 在每次创建实例时都调用工厂，生成新的列表或字典。

阶段 1：先区分不可变值和可变值

这一阶段的目标是决定字段默认值能不能直接写。先看一个适合直接写的例子。

from dataclasses import dataclass

@dataclass
class RetryConfig:
    max_times: int = 3
    timeout: float = 2.5
    enabled: bool = True
    remark: str = "default"

这些字段的默认值都是不可变值。创建多个实例时，它们不会因为某个实例修改字段而共享内部状态。

检查点很明确：如果字段默认值不需要被原地修改，直接写通常没问题。如果字段后续要 append、update、add，就要进入下一阶段。

阶段 2：用 field(default_factory=...) 生成独立对象

现在看可变字段。任务对象通常会带标签、扩展参数、运行记录。它们很适合用列表和字典表达，但默认值不能直接写成空列表或空字典。

from dataclasses import dataclass, field

@dataclass
class TaskConfig:
    name: str
    tags: list[str] = field(default_factory=list)
    options: dict[str, str] = field(default_factory=dict)
    warnings: set[str] = field(default_factory=set)

这里的 default_factory=list 不是提前准备一个列表，而是在每次创建 TaskConfig 时调用 list()。所以每个实例都有自己的 tags。

a = TaskConfig(name="daily")
b = TaskConfig(name="weekly")

a.tags.append("report")
a.options["level"] = "normal"

print(a.tags)
print(b.tags)
print(a.options)
print(b.options)

输出应该是：

['report']
[]
{'level': 'normal'}
{}

检查点是：修改 a 的列表或字典，不会影响 b。这说明默认值已经按实例隔离。

阶段 3：给复杂默认值写工厂函数

有些默认值不是空容器，而是带初始内容的结构。比如任务默认要有一个来源字段和一个版本号。这时不要把字典直接写在字段上，可以写一个工厂函数。

from dataclasses import dataclass, field

def make_default_options() -> dict[str, str]:
    return {
        "source": "system",
        "version": "v1",
    }

@dataclass
class JobConfig:
    name: str
    options: dict[str, str] = field(default_factory=make_default_options)

这个函数每次都会返回一个新字典。读代码的人也能看出来：默认配置不是一个共享对象，而是按实例生成。

如果默认值依赖外部配置，建议把读取动作放在更上层完成，再显式传入 dataclass。字段工厂适合轻量、稳定、无副作用的初始化。

我的推荐流程

日常写 dataclass 时，可以按下面的流程走，避免每次都临时判断。

一个最小测试可以这样写：

def test_task_config_defaults_are_isolated():
    a = TaskConfig(name="a")
    b = TaskConfig(name="b")

    a.tags.append("hot")
    a.options["owner"] = "ops"
    a.warnings.add("slow")

    assert b.tags == []
    assert b.options == {}
    assert b.warnings == set()
    assert a.tags is not b.tags
    assert a.options is not b.options

这类测试很小，但能直接证明默认值没有在实例之间串数据。团队里写通用配置类时，建议把它放进单元测试。

容易踩坑

1. 看到空列表就顺手写在字段上

空列表看起来像一个普通默认值，但它是可变对象。只要后续会修改，就应该用 default_factory。

2. 工厂函数返回了同一个全局对象

工厂函数要返回新对象，不要返回提前定义好的全局列表或全局字典。否则问题只是从字段定义挪到了函数内部。

shared_tags: list[str] = []

def bad_tags() -> list[str]:
    return shared_tags

更稳的写法是：

def make_tags() -> list[str]:
    return []

3. 把业务配置读取放进字段工厂

字段工厂最好保持轻量。如果创建对象时会读取文件、访问网络或依赖复杂环境，排查问题会变难。可以在外层准备好配置，再传给 dataclass。

4. 只看运行没报错，不验证实例隔离

默认值问题的危险点在于短期内不一定报错。创建两个实例、修改其中一个，是最直接的验证方式。

速查表

总结一句话：写 dataclass 默认值时，先问这个字段会不会被原地修改。不会修改的简单值可以直接写；会修改的容器或对象，用 field(default_factory=...) 生成新对象，再用两个实例做隔离验证。这个流程稳定、清晰，也方便后续维护。