Python dataclass 高级避坑指南：从 default_factory、frozen、slots 到哈希灾难

Python dataclass 高级避坑指南：从 default_factory、frozen、slots 到哈希灾难

在 Python 项目中，dataclass 往往给人一种"简单得不需要专门研究"的错觉。

很多开发者第一次使用它，大概都是从这样的代码开始：

from dataclasses import dataclass

@dataclass
class User:
    name: str
    age: int

几行代码就自动获得了 __init__、__repr__、__eq__ 等方法，相比手写普通类确实非常舒服。

于是很自然地，我们开始继续往里面添加列表、字典、frozen=True、slots=True，甚至把 dataclass 对象直接塞进 dict 和 set。

真正危险的地方，也往往从这里开始。

比如下面这段代码：

from dataclasses import dataclass

@dataclass
class Job:
    tags: list[str] = []

这里到底有什么问题？

进一步追问：

• default_factory 为什么存在？
• frozen=True 是否意味着对象真的不可变？
• slots=True 到底优化了什么？
• eq=True 与 unsafe_hash=True 为什么可能埋下严重 Bug？
• 一个 dataclass 被作为 dict 的 key 后，如果参与哈希计算的字段发生变化，会发生什么？

这些问题看起来零散，实际上都指向同一个核心：

dataclass 帮你生成了代码，但它不会替你维护对象语义。

本文就围绕这些问题，系统拆解 Python dataclass 最容易被忽略、同时也最值得高级开发者掌握的一组坑。

---

一、先看第一颗雷：tags: list[str] = []

我们从最经典的例子开始：

from dataclasses import dataclass

@dataclass
class Job:
    tags: list[str] = []

在现代 Python 中，这段代码通常不会等到你创建对象时才出问题，而是在定义 dataclass 时就直接报错：

ValueError: mutable default <class 'list'> for field tags is not allowed:
use default_factory

为什么 Python 要主动禁止它？

因为如果允许这样写，[] 并不是"每创建一个 Job 就创建一个新列表"，而是：

类定义执行时只创建一次这个列表，然后所有实例共享它。

这其实是 Python 默认参数问题的同一种语义陷阱。

假设我们手写一个普通类：

class Job:
    def __init__(self, tags=[]):
        self.tags = tags

然后：

job1 = Job()
job2 = Job()

job1.tags.append("python")

print(job1.tags)
print(job2.tags)

结果会是：

['python']
['python']

甚至：

print(job1.tags is job2.tags)

结果为：

True

两个对象本来毫不相关，却共享了同一个列表。

这在业务系统中非常可怕。

例如任务管理系统里：

job1 = Job()
job2 = Job()

你给第一个任务增加：

job1.tags.append("urgent")

第二个任务莫名其妙也拥有了 "urgent"。

如果这种 Bug 出现在缓存、权限、任务调度、订单标签等场景里，排查起来往往非常痛苦。

---

二、default_factory 为什么存在？

正确方式是：

from dataclasses import dataclass, field

@dataclass
class Job:
    tags: list[str] = field(default_factory=list)

现在：

job1 = Job()
job2 = Job()

job1.tags.append("python")

print(job1.tags)
print(job2.tags)

结果：

['python']
[]

并且：

print(job1.tags is job2.tags)

返回：

False

这就是 default_factory 存在的根本原因。

1. 普通 default 是一个"值"

例如：

@dataclass
class Config:
    retry: int = 3

可以理解为：

retry = 3

数字、字符串、元组等不可变对象通常没有共享修改的问题。

但对于：

[]
{}
set()

这样的可变对象，直接复用同一个实例就非常危险。

---

2. default_factory 是一个"创建值的函数"

这里：

field(default_factory=list)

不要理解成：

tags = list

更准确地说，它表示：

每次实例化对象时，调用一次 list()。

近似理解：

class Job:
    def __init__(self):
        self.tags = list()

于是每个对象都会获得自己的列表。

同理：

@dataclass
class User:
    permissions: set[str] = field(default_factory=set)
    metadata: dict[str, str] = field(default_factory=dict)

---

3. default_factory 不只能使用 list

它可以接收任何无参数可调用对象。

例如：

from dataclasses import dataclass, field
from datetime import datetime

@dataclass
class Task:
    created_at: datetime = field(default_factory=datetime.now)

注意这里必须写：

default_factory=datetime.now

而不是：

default_factory=datetime.now()

两者意义完全不同。

前者保存的是函数：

datetime.now

每次创建对象时执行一次。

后者：

datetime.now()

则会立刻执行。

类似地，也可以写：

@dataclass
class Config:
    settings: dict[str, bool] = field(
        default_factory=lambda: {
            "debug": False,
            "cache": True,
        }
    )

---

三、一个更隐蔽的问题：嵌套对象

假设：

@dataclass
class Job:
    tags: list[str] = field(default_factory=list)

这已经解决了最外层列表共享的问题。

但下面这样：

template = {"retry": []}

@dataclass
class Task:
    config: dict = field(
        default_factory=lambda: template.copy()
    )

仍然可能出问题。

因为：

dict.copy()

只是浅拷贝。

测试：

task1 = Task()
task2 = Task()

task1.config["retry"].append(1)

print(task2.config)

你可能得到：

{'retry': [1]}

原因是：

task1.config is not task2.config

虽然成立，但：

task1.config["retry"] is task2.config["retry"]

仍然成立。

所以 default_factory 解决的是：

字段默认对象创建时机的问题。

它并不会自动解决深层嵌套可变对象共享的问题。

更稳妥的方法是直接创建完整对象：

@dataclass
class Task:
    config: dict = field(
        default_factory=lambda: {
            "retry": []
        }
    )

或者在确有必要时使用深拷贝。

---

四、frozen=True：真的不可变吗？

接下来是第二个极容易产生误解的功能。

from dataclasses import dataclass

@dataclass(frozen=True)
class User:
    name: str
    age: int

创建：

user = User("Alice", 25)

然后：

user.age = 26

会抛出：

FrozenInstanceError

于是很多人得出结论：

frozen=True 相当于 Python 的 immutable object。

这个结论并不完整。

---

五、frozen=True 只是"禁止常规字段赋值"

看下面这个例子：

from dataclasses import dataclass, field

@dataclass(frozen=True)
class Job:
    name: str
    tags: list[str] = field(default_factory=list)

现在：

job = Job("crawler")

执行：

job.name = "worker"

会失败。

但：

job.tags.append("python")

完全可以成功。

最终：

print(job)

可能是：

Job(name='crawler', tags=['python'])

所以：

frozen 冻结的是 dataclass 字段绑定，而不是递归冻结字段指向的对象。

换句话说：

job.tags = ["new"]

不允许。

但：

job.tags.append("new")

允许。

因为第二种操作没有修改 job.tags 这个引用本身，而是在修改它所指向的列表对象。

---

六、真正追求不可变，应使用不可变字段

如果你的对象需要可靠地作为 Value Object，例如：

@dataclass(frozen=True)
class Coordinate:
    x: int
    y: int

没有问题，因为：

int

本身不可变。

但如果是：

@dataclass(frozen=True)
class Job:
    tags: list[str]

语义就值得警惕。

更好的设计可能是：

@dataclass(frozen=True)
class Job:
    tags: tuple[str, ...]

使用：

job = Job(("python", "backend"))

这样：

job.tags.append("async")

压根不存在这种操作。

如果需要新增 tag，更符合不可变设计的方法是构造新对象：

from dataclasses import replace

new_job = replace(
    job,
    tags=job.tags + ("async",)
)

这种设计在：

• 配置对象
• 缓存 Key
• 领域模型中的 Value Object
• 并发程序
• 函数式编程
• 状态快照

等场景中尤其有价值。

---

七、frozen=True 甚至可以被绕过

严格来说，frozen=True 并不是底层完全不可修改。

例如：

@dataclass(frozen=True)
class User:
    name: str

正常情况下：

user.name = "Bob"

失败。

但：

object.__setattr__(user, "name", "Bob")

却可以绕过 dataclass 的限制。

例如：

user = User("Alice")

object.__setattr__(user, "name", "Bob")

print(user)

结果：

User(name='Bob')

所以 frozen=True 更准确的理解应该是：

一种 API 级别、语义级别的不可变约束，而不是安全边界。

它是用来告诉开发者：

"这个对象在正常业务逻辑中不应该发生字段重新赋值。"

而不是防御恶意代码。

事实上，在某些高级场景中，我们甚至会在 __post_init__ 中主动使用 object.__setattr__。

例如：

@dataclass(frozen=True)
class Rectangle:
    width: float
    height: float
    area: float = field(init=False)

    def __post_init__(self):
        object.__setattr__(
            self,
            "area",
            self.width * self.height,
        )

调用：

rect = Rectangle(4, 5)

print(rect.area)

输出：

20

这是一种合理的高级用法。

---

八、slots=True 到底有什么意义？

接下来看看：

@dataclass(slots=True)
class User:
    name: str
    age: int

很多教程只会告诉你一句：

slots 可以节省内存。

没错，但这句话远远不够。

---

九、普通 Python 对象为什么比较"重"？

普通对象通常拥有：

obj.__dict__

比如：

@dataclass
class User:
    name: str
    age: int

执行：

user = User("Alice", 25)

print(user.__dict__)

结果：

{
    'name': 'Alice',
    'age': 25
}

这意味着对象属性主要保存在一个动态字典里。

它的优势是非常灵活。

甚至：

user.city = "Shanghai"

也是允许的。

因为 Python 可以直接往 __dict__ 里增加：

"city": "Shanghai"

但代价就是：

• 每个实例维护额外字典；
• 占用更多内存；
• 属性结构完全动态；
• 某些属性访问优化空间受到限制。

---

十、slots=True 限制实例布局

使用：

@dataclass(slots=True)
class User:
    name: str
    age: int

以后，实例通常不再需要常规的：

__dict__

你也不能随意执行：

user.city = "Shanghai"

通常会得到：

AttributeError

因为类已经声明：

这个对象就只有这些 slot。

逻辑上可以想象成：

User instance
┌──────────────┐
│ name slot    │
├──────────────┤
│ age slot     │
└──────────────┘

而普通对象更接近：

User instance
       │
       ▼
    __dict__
┌─────────────────┐
│ "name": "Alice" │
│ "age": 25       │
└─────────────────┘

因此，当系统需要创建几十万甚至几百万个同类对象时，slots=True 的价值就会非常明显。

例如：

@dataclass(slots=True)
class Point:
    x: float
    y: float

如果 GIS、游戏、行情系统或者数据处理任务中要创建：

5,000,000 个 Point

每个实例省下一些内存，乘以数百万以后就是非常可观的差距。

---

十一、什么时候值得使用 slots=True？

我一般建议在以下情况下重点考虑：

实例数量巨大
        │
        ├──► 数据模型固定
        │
        ├──► 不依赖动态属性
        │
        ├──► 生命周期较长
        │
        └──► 对内存/性能敏感
                │
                ▼
            slots=True

典型场景包括：

• 大规模数据对象；
• AST 节点；
• 游戏实体；
• 网络协议对象；
• 金融行情数据；
• ORM 之外的领域实体；
• 高性能缓存结构。

但如果只是后台管理系统：

User
Order
Config

对象数量并不大，那么有没有 slots 往往不会决定系统性能。

不要为了"看起来高级"而机械加入：

@dataclass(slots=True)

性能优化最重要的原则仍然是：

先测量，再优化。

---

十二、slots=True 还有一些工程上的副作用

例如依赖：

obj.__dict__

的代码可能失效。

下面的做法：

data = obj.__dict__

对 slots 对象并不可靠。

如果目的是把 dataclass 转为字典，更推荐：

from dataclasses import asdict

data = asdict(obj)

此外，在现代 Python 中，@dataclass(slots=True) 的实现还涉及创建具有 slots 的类，因此当项目存在复杂：

• 继承；
• 元类；
• __init_subclass__；
• 弱引用；

设计时，需要额外测试，而不能把它简单理解成一个"无副作用的性能开关"。

---

十三、真正危险的部分来了：eq=True

dataclass 默认：

eq=True

例如：

@dataclass
class User:
    name: str
    age: int

可以直接：

u1 = User("Alice", 25)
u2 = User("Alice", 25)

print(u1 == u2)

返回：

True

因为 dataclass 会根据字段生成类似这样的比较逻辑：

return (
    self.name,
    self.age,
) == (
    other.name,
    other.age,
)

这对于值对象非常舒服。

但麻烦在于：

相等性会进一步影响哈希语义。

而哈希语义直接决定一个对象能不能安全地作为：

dict key

或者：

set element

---

十四、先理解 Python 的哈希契约

假设：

a == b

成立。

那么 Python 对哈希对象有一个非常重要的要求：

hash(a) == hash(b)

也必须成立。

否则：

dict
set

这样的哈希表结构就无法正常工作。

更重要的是：

只要一个对象已经位于 dict 或 set 中，它的哈希值在该对象作为成员期间就必须保持稳定。

这是理解 unsafe_hash=True 的关键。

---

十五、为什么普通可变 dataclass 默认不能 hash？

例如：

@dataclass
class User:
    name: str
    age: int

然后：

user = User("Alice", 25)

hash(user)

通常会得到：

TypeError: unhashable type: 'User'

这不是 dataclass "功能不完整"。

恰恰相反，这是 Python 在保护你。

因为：

user.age = 26

完全合法。

如果 hash(user) 又依赖：

name
age

那么字段改变后，hash 也会改变。

一旦它已经被放进哈希表，灾难就开始了。

---

十六、unsafe_hash=True 为什么名字里有 unsafe？

例如：

@dataclass(unsafe_hash=True)
class User:
    name: str
    age: int

现在：

user = User("Alice", 25)

print(hash(user))

可以得到一个 hash。

但是注意：

old_hash = hash(user)

user.age = 26

new_hash = hash(user)

print(old_hash == new_hash)

大概率为：

False

于是问题来了：

如果修改之前，已经执行：

cache = {
    user: "some data"
}

会发生什么？

---

十七、项目事故现场：dataclass 作为 dict key 后发生字段变化

我们来看一个完整案例。

from dataclasses import dataclass

@dataclass(unsafe_hash=True)
class Job:
    job_id: int
    priority: int

创建：

job = Job(
    job_id=1001,
    priority=1,
)

然后：

jobs = {
    job: "running"
}

此时：

print(jobs[job])

正常输出：

running

随后业务运行过程中修改优先级：

job.priority = 10

再执行：

print(jobs[job])

你很可能遇到：

KeyError

最诡异的地方是什么？

这个对象明明还在字典里！

例如遍历：

for key in jobs:
    print(key)

可能仍然看到：

Job(job_id=1001, priority=10)

但：

job in jobs

却可能返回：

False

这就是哈希表的不变量被破坏之后出现的经典问题。

---

十八、为什么 dict "找不到明明存在的对象"？

理解这个 Bug，需要简单理解 Python 哈希表。

当执行：

jobs[job] = "running"

Python 首先计算：

hash(job)

假设得到：

123456

然后根据这个 hash 决定对象应该放入哈希表中的哪个位置。

可以简化理解为：

job
 │
 ▼
hash(job)
 │
 ▼
123456
 │
 ▼
bucket #42
 │
 ▼
Job(job_id=1001, priority=1)

后来执行：

job.priority = 10

如果 hash 变成：

987654

那么查找：

jobs[job]

时，Python 会根据新的 hash 去寻找：

job
 │
 ▼
hash(job)
 │
 ▼
987654
 │
 ▼
bucket #87
 │
 ▼
没有找到

然而那个对象实际上还躺在旧位置：

bucket #42

于是：

对象物理上仍然存在于 dict 内部，但是按照当前 hash 已经无法正常定位它。

这类 Bug 最危险的一点是：

没有任何线程问题、数据库问题或网络问题，单纯是对象语义已经违反了哈希表规则。

---

十九、甚至可能进一步污染 dict

更糟糕的是，你可能再次执行：

jobs[job] = "finished"

由于新的 hash 已经指向另外一个搜索位置，哈希表可能无法识别旧条目。

于是内部状态会变得更加违反开发者直觉。

从业务代码看，你以为：

job

就是那个 job。

但从哈希表结构看：

旧 hash 对应的成员

和：

当前 hash 对应的查找

已经脱节了。

因此可以记住一句非常重要的 Python 实践原则：

作为 dict key 或 set 成员的对象，其参与 __hash__ 和 __eq__ 的状态不应该发生变化。

---

二十、那么 unsafe_hash=True 什么时候能用？

并不是说它永远不能使用。

关键在于理解：

unsafe_hash=True

真正表达的意思不是：

"请让我可以作为 dict key。"

而更接近：

"我知道这个对象表面上是可变的，但我确认参与哈希计算的逻辑状态不会变化，请强制帮我生成 hash。"

这是一种开发者主动承担责任的设计。

例如：

@dataclass(unsafe_hash=True)
class User:
    user_id: int
    name: str = field(
        compare=False,
        hash=False,
    )

理论上，如果只有：

user_id

参与相等性和哈希，而 user_id 永远不会修改，那么对象作为 key 可以相对安全。

比如：

user = User(
    user_id=1001,
    name="Alice",
)

users = {user: "online"}

user.name = "Alice Chen"

因为：

name

没有参与 hash：

hash(user)

不会因为名字修改而变化。

不过从设计角度来说，我仍然更推荐把 Key 单独建模。

---

二十一、更好的方案：不要拿整个业务对象当 Key

例如原代码：

jobs: dict[Job, str]

很多时候其实不如：

jobs: dict[int, str]

直接使用：

job_id

作为 Key。

例如：

@dataclass
class Job:
    job_id: int
    priority: int
    status: str

jobs: dict[int, Job] = {}

job = Job(
    job_id=1001,
    priority=1,
    status="running",
)

jobs[job.job_id] = job

后面无论修改：

job.priority = 10
job.status = "finished"

都不会破坏：

jobs[1001]

的定位。

这是业务系统中极其推荐的方式：

让稳定身份作为 key，让可变状态作为 value。

---

二十二、另一种方案：设计真正不可变的 Key

如果业务确实需要组合字段作为 Key，例如：

tenant_id + task_id

可以专门创建：

@dataclass(frozen=True, slots=True)
class JobKey:
    tenant_id: int
    job_id: int

然后：

jobs: dict[JobKey, str] = {}

key = JobKey(
    tenant_id=10,
    job_id=1001,
)

jobs[key] = "running"

这个设计明显比：

@dataclass(unsafe_hash=True)
class Job:
    tenant_id: int
    job_id: int
    priority: int
    status: str
    tags: list[str]

然后硬把整个 Job 塞进 dict 要可靠得多。

这里实际上体现了一条非常重要的软件设计原则：

身份
状态
行为

不要混在一个哈希对象里。

---

二十三、eq=True、frozen=True、unsafe_hash=True 到底是什么关系？

这是 dataclass 最容易让人混乱的一组配置。

可以简单记成：

配置	典型行为
eq=True, frozen=False	可比较，但通常不可 hash
eq=True, frozen=True	通常会生成 hash
eq=False	不生成字段级 equality
unsafe_hash=True	强制生成 hash，需要开发者自己保证安全

最常见的值对象：

@dataclass(frozen=True)
class Coordinate:
    x: int
    y: int

这是非常自然的。

因为：

Coordinate(1, 2) == Coordinate(1, 2)

为：

True

而且对象不会正常修改。

因此可以：

points = {
    Coordinate(1, 2): "A"
}

这种语义非常合理。

---

二十四、但是 frozen=True + 可变字段仍然可能失败

注意：

@dataclass(frozen=True)
class Job:
    name: str
    tags: list[str]

你可能以为：

frozen=True

所以可以放心作为 key。

但：

job = Job(
    "crawler",
    ["python"],
)

hash(job)

可能直接失败：

TypeError: unhashable type: 'list'

为什么？

生成 hash 时，逻辑类似：

hash((
    self.name,
    self.tags,
))

但：

list

本身不可哈希。

所以：

frozen=True 并不意味着所有字段自动可哈希。

如果一个对象要作为稳定哈希对象，最理想的字段通常也是：

int
str
bytes
tuple
frozenset
其他真正不可变且可 hash 的对象

---

二十五、compare=False 和 hash=False 是高级 dataclass 必学配置

假设：

@dataclass(frozen=True)
class FileRecord:
    path: str
    checksum: str
    metadata: dict

问题是：

metadata

不可哈希。

而且从业务语义看，metadata 可能根本不应该决定两个 FileRecord 是否属于同一个实体。

可以设计：

from dataclasses import dataclass, field

@dataclass(frozen=True)
class FileRecord:
    path: str
    checksum: str

    metadata: dict = field(
        default_factory=dict,
        compare=False,
        hash=False,
    )

这样 metadata 不参与：

==

也不参与：

hash()

例如：

a = FileRecord(
    path="/tmp/a.txt",
    checksum="abc",
    metadata={"size": 100},
)

b = FileRecord(
    path="/tmp/a.txt",
    checksum="abc",
    metadata={"size": 200},
)

print(a == b)

返回：

True

这到底对不对？

取决于你的领域语义。

这也是 dataclass 的关键：

不要先问 Python 会生成什么，要先问"业务上什么叫两个对象相等"。

---

二十六、一个工程案例：任务调度系统应该怎样设计？

假设我们正在开发一个任务调度器。

最初版本：

@dataclass(unsafe_hash=True)
class Job:
    id: int
    priority: int
    status: str

程序为了快速查找任务：

running_jobs = {
    job: timestamp
}

运行过程中：

job.priority += 1
job.status = "retrying"

突然：

job not in running_jobs

于是工程师开始排查：

是不是多线程问题？
是不是对象复制了？
是不是缓存失效？
是不是异步竞争？

最终发现只是：

Job hash 变化

导致哈希表失去定位能力。

更合理的重构方式是：

@dataclass(slots=True)
class Job:
    id: int
    priority: int
    status: str
    tags: list[str] = field(default_factory=list)

存储：

running_jobs: dict[int, Job] = {}

写入：

running_jobs[job.id] = job

状态可以自由变化：

job.priority += 1
job.status = "retrying"
job.tags.append("network")

但：

running_jobs[job.id]

始终稳定。

如果必须使用复合 key：

@dataclass(frozen=True, slots=True)
class JobKey:
    tenant_id: int
    job_id: int

业务对象：

@dataclass(slots=True)
class Job:
    key: JobKey
    priority: int
    status: str
    tags: list[str] = field(default_factory=list)

缓存：

running_jobs: dict[JobKey, Job] = {}

这时：

JobKey = 稳定身份
Job    = 可变状态

模型职责变得非常清晰。

---

二十七、推荐的 dataclass 设计模式

实践中，我比较推荐把 dataclass 分成三类。

第一类：Value Object

例如坐标、金额、版本号：

@dataclass(
    frozen=True,
    slots=True,
)
class Coordinate:
    x: float
    y: float

特点：

不可变
按值比较
可以安全 hash
适合作为 dict key

---

第二类：Mutable Entity

例如用户、订单、任务：

@dataclass(slots=True)
class Job:
    id: int
    status: str
    priority: int
    tags: list[str] = field(default_factory=list)

特点：

有稳定 ID
状态允许变化
一般不应该作为 dict key

建议：

dict[int, Job]

而不是：

dict[Job, ...]

---

第三类：DTO / 数据传输对象

例如：

@dataclass(slots=True)
class CreateUserRequest:
    name: str
    email: str

主要职责是：

接收数据
传递数据
减少样板代码

通常不应该塞进复杂：

hash
继承
元编程

逻辑。

dataclass 越简单，DTO 越好维护。

---

二十八、几个容易忽略的最佳实践

1. 可变默认值永远优先检查 default_factory

看到：

list
dict
set

第一反应应该是：

field(default_factory=...)

例如：

tags: list[str] = field(default_factory=list)

---

2. 不要把 frozen=True 当深度不可变

下面这个对象：

@dataclass(frozen=True)
class A:
    values: list[int]

依然可以：

a.values.append(1)

需要深层不可变语义时，应选择：

tuple
frozenset

等数据结构。

---

3. unsafe_hash 出现时应该提高警惕

如果 Code Review 看到：

unsafe_hash=True

我会立刻追问三个问题：

哪些字段参与 hash？

这些字段是否可能变化？

为什么必须拿整个对象当 dict key？

如果团队回答不了这三个问题，最好不要使用。

---

4. 大量实例才重点考虑 slots=True

slots 是一种有价值的对象布局优化，但不是所有 dataclass 的必选项。

更合理的流程是：

发现内存或对象创建压力
        ↓
profile
        ↓
确认大量实例是问题来源
        ↓
评估 slots=True
        ↓
benchmark
        ↓
上线

而不是看到教程推荐就全项目批量修改。

---

5. 相等性应该来自领域，而不是装饰器默认值

假设：

@dataclass
class User:
    id: int
    name: str

默认情况下：

User(1, "Alice") == User(1, "Bob")

结果是：

False

但是业务上两个对象只要：

id == 1

是不是就应该认为它们表示同一个用户？

这个问题没有 Python 层面的标准答案。

它属于领域建模。

因此更重要的问题不是：

dataclass 的 eq=True 默认做什么？

而是：

这个业务对象的 identity 到底是什么？

---

二十九、一张图看懂 dataclass 的设计决策

可以用下面这套思路判断：

               这个对象字段会变化吗？
                       │
             ┌─────────┴─────────┐
             │                   │
            不会                 会
             │                   │
             ▼                   ▼
        frozen=True        frozen=False
             │                   │
             │                   ▼
             │             是否大量实例？
             │              │         │
             │             是         否
             │              │         │
             │        slots=True     默认即可
             │
             ▼
       是否作为 dict key？
         │          │
        是          否
         │
         ▼
 所有参与 hash 的字段
 是否真正不可变？
     │       │
    是       否
     │       │
     ▼       ▼
   可考虑    重新设计
    hash     Key 模型

其中最重要的分支其实是：

"字段是否真正不可变？"

而不是有没有写：

frozen=True

---

三十、一个更成熟的 Job 模型

综合本文内容，一个实际项目中相对稳健的设计可能是：

from dataclasses import dataclass, field
from datetime import datetime


@dataclass(
    frozen=True,
    slots=True,
)
class JobKey:
    tenant_id: int
    job_id: int


@dataclass(slots=True)
class Job:
    key: JobKey

    priority: int = 0
    status: str = "pending"

    tags: list[str] = field(
        default_factory=list
    )

    created_at: datetime = field(
        default_factory=datetime.now
    )

    metadata: dict[str, str] = field(
        default_factory=dict
    )

缓存：

jobs: dict[JobKey, Job] = {}

创建：

job = Job(
    key=JobKey(
        tenant_id=100,
        job_id=2001,
    )
)

jobs[job.key] = job

随后业务状态任意改变：

job.priority = 10
job.status = "running"
job.tags.append("python")
job.metadata["worker"] = "node-01"

Key 仍然稳定：

assert jobs[job.key] is job

这比给整个 Job 添加：

unsafe_hash=True

要清晰得多。

---

三十一、最终总结：dataclass 不只是"少写几个 __init__"

很多 Python 教程把 dataclass 介绍成：

自动帮我们生成构造函数的工具。

这个理解只覆盖了它最表面的价值。

真正进入工程项目后，你会发现 dataclass 背后其实涉及一系列 Python 对象模型中的核心问题：

默认值生命周期
对象可变性
相等性
对象身份
哈希契约
内存布局
领域建模

回到文章开头：

@dataclass
class Job:
    tags: list[str] = []

这个错误看似只是一个：

mutable default

问题。

但如果继续深入，你会发现它真正提醒我们的，是 Python 开发中一条非常重要的原则：

理解对象的生命周期，比记住装饰器参数更重要。

关于本文四个核心问题，可以最终归纳为：

default_factory 为什么存在？

因为可变默认对象不能在多个实例之间意外共享。default_factory 将"默认值"转换成"每次实例化时调用的对象工厂"。

frozen=True 是否真的不可变？

不是深度不可变。它主要禁止正常的字段重新赋值，字段内部的可变对象依然可以修改，而且高级代码还能通过 object.__setattr__ 绕过限制。

slots=True 有什么意义？

它让实例采用更固定的属性布局，通常可以减少实例内存开销、限制动态属性，并在大量实例场景下获得实际价值。

eq=True + unsafe_hash=True 为什么危险？

因为如果参与相等性和哈希计算的可变字段发生变化，对象的 hash 也可能改变。一旦对象已经作为 dict key 或 set 成员存在，就可能破坏哈希表的不变量。

最后送给正在学习 Python 编程，或者已经在复杂 Python 项目中摸爬滚打的开发者一句实践建议：

不要问"dataclass 能不能这样写"，而要问"这个对象应该拥有什么语义"。

当你能够主动区分：

Value Object
Entity
DTO
Stable Key
Mutable State

的时候，dataclass 才真正从一个"减少样板代码的语法糖"，变成你进行 Python 工程设计时非常锋利的一把工具。

这也是从"会写 Python"，走向"真正理解 Python"的一个重要分水岭。

---

延伸思考

如果你正在做 Python 实战项目，不妨检查一下自己的代码：

@dataclass(unsafe_hash=True)

到底出现了多少次？

再继续问：

这些对象真的应该作为 Key 吗？

以及：

参与 hash() 的字段，在对象进入 dict 或 set 后，真的永远不会变化吗？

很多隐藏数月甚至数年的线上 Bug，往往就藏在这两个问题的答案里。

而这，也正是 Python 最有趣的地方------看似简洁的语法背后，总有一整套值得继续探索的对象模型与工程哲学。