下面这句代码：

from dataclasses import dataclass

看起来很短，但它背后其实代表了 Python 里一种非常重要的建模方式。它的意思是：从标准库 dataclasses 模块中，导入一个叫 dataclass 的装饰器。这个装饰器的作用，是根据你在类里写好的字段定义，自动帮你生成一批常见的特殊方法，比如 __init__()、__repr__()、__eq__()，必要时还可以生成排序、哈希、模式匹配相关的能力。dataclasses 在 Python 3.7 被加入标准库，它建立在类型注解语法之上；按照当前 Python 3.14 官方文档，@dataclass 还支持 match_args、kw_only、slots、weakref_slot 等参数。

如果用一句更形象的话来理解，dataclass 可以被看成“更适合写数据对象的类写法”。PEP 557 里把它描述为一种近似“带默认值的、可变的 namedtuple”的东西，但它又比 namedtuple 更自由，因为它仍然是普通的 Python 类：你可以继承、写方法、加文档字符串，也可以配合静态类型检查器一起使用。也就是说，dataclass 并不是一种全新的面向对象机制，而是一个帮你减少模板代码的增强工具。

最基础的写法是这样的：

from dataclasses import dataclass

@dataclass
class User:
    name: str
    age: int
    city: str = "Taipei"

这段代码最厉害的地方，不在于你写了多少，而在于你没写的那些东西。虽然你没有手写构造函数，但 @dataclass 会按字段顺序自动生成一个大致等价的 __init__(self, name, age, city="Taipei")；你没有写打印格式，它会自动提供可读性很强的 __repr__()；你没有写相等性比较，它会把对象当作字段元组来比较。官方文档给出的示例就明确说明了这一点：字段顺序会影响生成的方法，而字段是通过带类型注解的类变量识别出来的。

这就是 dataclass 最适合的场景：你的类主要是“装数据”的，同时还希望保留类的方法和面向对象结构。比如用户资料、订单记录、配置项、坐标点、树节点、API 返回结果、数据库传输对象，这些都非常适合。以前你可能要写很多重复代码：

class User:
    def __init__(self, name, age, city="Taipei"):
        self.name = name
        self.age = age
        self.city = city

    def __repr__(self):
        return f"User(name={self.name!r}, age={self.age!r}, city={self.city!r})"

而 @dataclass 的核心价值，就是把这一类高度机械、重复、低信息量的代码交给解释器生成。

很多初学者第一次看到它时，会误以为 dataclass 是“运行时类型检查工具”。其实不是。dataclass 使用类型注解，主要是为了识别哪些属性属于字段；除少数特殊情况外，它并不会在运行时检查你写的类型是否真的匹配。官方文档明确说了：除了少数例外，@dataclass 不会检查变量注解里写的类型本身。也就是说，name: str 更多是在表达意图、支持 IDE 和类型检查器，而不是自动拦截错误输入。

dataclass 的一个核心概念叫“字段”。只要类变量有类型注解，它通常就会被当作字段参与构造、打印、比较等行为。字段顺序非常重要，因为生成出来的 __init__() 参数顺序、__repr__() 输出顺序、比较顺序，都是按你在类中声明的先后来的。如果你给某些字段设置了默认值，那么所有没有默认值的字段必须写在前面；如果一个“无默认值字段”出现在“有默认值字段”之后，dataclass 会抛出 TypeError。这个规则不仅在单个类里成立，在继承场景下也成立。

例如下面这样就是错误写法：

from dataclasses import dataclass

@dataclass
class BadUser:
    name: str = "anonymous"
    age: int

因为 age 没有默认值，却出现在有默认值的 name 后面。正确做法是把无默认值字段放在前面，或者把所有需要可选的字段都补上默认值。这个规则本质上是在保证生成出来的 __init__() 仍然符合 Python 函数参数的基本规则。

当默认语义不够用时，就要用 field()。field() 不是另一种字段类型，而是字段的“精细配置器”。它允许你控制一个字段是否进入 __init__()，是否出现在 __repr__() 中，是否参与比较和哈希，是否是仅限关键字参数，等等。当前官方文档中的 field() 参数包括 default、default_factory、init、repr、hash、compare、metadata、kw_only 和 doc。其中 doc 是 Python 3.14 新增的字段文档字符串支持。

举个常见例子：

from dataclasses import dataclass, field

@dataclass
class Product:
    name: str
    price: float
    internal_id: str = field(repr=False)

这样 internal_id 仍然存在于对象里，但打印对象时不会显示它。再比如：

@dataclass
class Point:
    x: int
    y: int
    distance: float = field(init=False)

    def __post_init__(self):
        self.distance = (self.x ** 2 + self.y ** 2) ** 0.5

这里 distance 不会出现在构造参数里，而是在初始化完成后再计算。__post_init__() 就是 dataclass 提供的后处理钩子：如果定义了它，生成的 __init__() 会在字段赋值完成后自动调用它。它最常见的用途，是计算依赖其他字段的派生值，或者在初始化阶段做额外整理。

__post_init__() 在继承中也非常有用。官方文档特别指出，dataclass 自动生成的 __init__() 不会去调用普通基类的 __init__()。如果你的父类是一个普通类，而且它的构造函数必须执行，那么通常要在子类的 __post_init__() 里手动调用 super().__init__(...)。但如果父类本身也是 dataclass，那么子类通常会自动接管父类字段的初始化。这个细节很重要，因为不少人会误以为 dataclass 像传统继承那样会自动链式调用所有父类构造。其实不是。
另一个高频知识点，是可变默认值。很多 Python 新手都写过这样的代码：

@dataclass
class Bag:
    items: list = []

这在 dataclass 里会出问题。原因不是 dataclass 特有，而是 Python 类默认值本来就会放在类属性层面，如果默认值是列表、字典、集合这种可变对象，不同实例可能共享同一份数据。官方文档说明：为避免这类常见错误，@dataclass 会在检测到不合适的默认值时抛出错误；正确方式是用 default_factory，让每个实例在创建时得到一个新的对象。

正确写法是：

from dataclasses import dataclass, field

@dataclass
class Bag:
    items: list = field(default_factory=list)

这里的 default_factory=list 意思是：当需要默认值时，调用 list() 生成一个新的空列表。官方文档明确指出，default_factory 必须是一个零参数可调用对象，它会在需要默认值时被调用。对于 list、dict、set 这类字段，这几乎是标准写法。

如果你希望对象在比较时表现得像“值对象”，dataclass 会非常顺手。默认 eq=True，这意味着它会生成 __eq__()，并把两个实例按字段元组来比较；比较要求双方是同一类型。如果再设置 order=True，它还会进一步生成 <、<=、>、>= 这些排序方法，同样按字段顺序进行比较。不过官方也说明了：如果 order=True 而 eq=False，会直接抛出 ValueError，因为排序通常建立在可比较相等性的基础上。
例如：

from dataclasses import dataclass

@dataclass(order=True)
class Score:
    math: int
    english: int

这样 Score(90, 80) < Score(95, 70) 就会按字段顺序参与比较。这种设计很适合“由若干有序字段共同定义排序”的场景，但如果你的业务排序规则更复杂，比如按总分、按等级、按时间优先级，那通常还是手写比较逻辑更清晰。

再往前一步，就是 frozen=True。它的语义接近“只读对象”。当你设置这个参数后，dataclass 会给类加上阻止赋值的机制，对字段重新赋值会触发 FrozenInstanceError。不过官方文档也明确提醒：这并不等于 Python 真正意义上的绝对不可变，它只是“模拟不可变”；并且因为初始化时要改用 object.__setattr__()，会有一点点性能代价。

from dataclasses import dataclass

@dataclass(frozen=True)
class Config:
    host: str
    port: int

这种写法很适合配置对象、坐标值对象、标识对象等“创建之后不希望随意修改”的模型。它还有一个重要副作用：__hash__() 的生成规则会受 eq 和 frozen 共同影响。官方规则是：如果 eq=True 且 frozen=True，dataclass 默认会生成哈希方法；如果 eq=True 但 frozen=False，则会把 __hash__ 设为 None，让对象不可哈希；如果 eq=False，则保留父类的哈希行为。unsafe_hash=True 可以强制生成哈希，但官方也强调这是一个需要谨慎使用的特殊选项。

除了普通字段，dataclass 还识别两种“伪字段”。第一种是 ClassVar。如果某个属性被注解为 typing.ClassVar，它会被视为类变量，而不是实例字段；它不会进入 __init__()，也不会出现在 fields() 结果里。第二种是 InitVar。它只参与初始化过程：会成为 __init__() 的参数，并且可以被传给 __post_init__()，但不会真正作为实例字段保存下来。

这两个概念非常实用。比如：

from dataclasses import dataclass, InitVar
from typing import ClassVar

@dataclass
class App:
    version: ClassVar[str] = "1.0"
    name: str
    raw_password: InitVar[str]

    def __post_init__(self, raw_password):
        # 这里可以做加密、校验等逻辑
        pass

这里 version 更像全类共享的常量，而 raw_password 更像一次性输入参数。它们都不是常规意义上的“数据字段”，因此 dataclass 会用特殊方式对待。

继承方面，dataclass 的行为也很有特点。官方文档说明，创建子类时，它会按逆 MRO 顺序收集所有 dataclass 基类的字段，再把子类自己的字段追加进去，最后用这个合并后的有序字段映射生成方法。因为字段有顺序，子类可以覆盖父类同名字段，且最终方法以合并后的顺序为准。

例如父类里有 x、y，子类里新增 z，并重新定义 x，那么最终顺序可能是 x, y, z，而 x 的类型和默认值以子类定义为准。这种行为使 dataclass 的继承既保持了普通类的直觉，又能稳定地生成构造函数和比较逻辑。

从 Python 3.10 开始，dataclass 增加了几个很现代的参数。match_args=True 会生成 __match_args__，让 dataclass 更自然地参与结构化模式匹配；kw_only=True 可以把字段变成仅限关键字传参；同时还提供了 KW_ONLY 哨兵，用于把它后面的字段都标记为关键字参数。官方文档还说明：关键字字段不会被包含进 __match_args__。

例如：

from dataclasses import dataclass, KW_ONLY

@dataclass
class Point:
    x: float
    _: KW_ONLY
    y: float
    z: float

这时实例化时必须写成 Point(1.0, y=2.0, z=3.0)，而不能把 y 和 z 当作普通位置参数。这在大型项目里非常有价值，因为它能让构造调用更清晰、更不容易写错。
另一个值得了解的参数是 slots=True。官方文档指出，开启后 dataclass 会为类生成 __slots__，并返回一个新的类对象而不是原类；如果类本身已经定义了 __slots__，会报 TypeError。这通常用于减少实例内存占用、限制动态属性创建。与之相关的 weakref_slot=True 则会额外添加 __weakref__ 槽位，但它只能和 slots=True 一起使用。slots 和 weakref_slot 分别是在 Python 3.10 和 3.11 中加入的。
在实际开发中，dataclass 还配了一组很好用的工具函数。asdict() 可以把 dataclass 实例递归转换成字典；astuple() 会递归转换成元组；replace() 可以基于现有实例创建一个替换了部分字段的新实例，而且它会通过 dataclass 的 __init__() 来创建新对象，因此 __post_init__() 也会被调用；is_dataclass() 可以判断某个类或对象是不是 dataclass。

例如：

from dataclasses import dataclass, asdict, replace

@dataclass
class User:
    name: str
    age: int

u1 = User("Alice", 20)
u2 = replace(u1, age=21)

print(asdict(u1))   # {'name': 'Alice', 'age': 20}
print(u2)           # User(name='Alice', age=21)

这种“不可变式更新”写法，在配置对象、状态对象、消息对象里特别方便。即便你没有设置 frozen=True，replace() 仍然是一种很优雅的复制修改方式。

当然，dataclass 也不是所有场景都适合。PEP 557 本身就强调，它不是为了取代所有相关库，也不是所有类都应该变成数据类。一个经验判断是：如果你的类主要职责是“存数据，并围绕这些数据做少量辅助行为”，那 dataclass 很适合；如果你的类内部状态变化复杂、封装要求高、需要大量自定义属性控制、或者核心价值在行为而不是数据，那么普通类往往更合适。它和 attrs、pydantic 这类库也不是竞争性替代关系，而是标准库里覆盖“简单而高频”需求的方案。

如果把整件事浓缩成一句话，那么 from dataclasses import dataclass 导入的，不只是一个装饰器，而是一种“把数据模型写得更简洁、更清晰、更 Pythonic”的方式。它让类定义重新回到最重要的部分：这个对象有什么字段，这些字段如何初始化，哪些字段参与比较，哪些字段是派生出来的，哪些字段只是初始化时临时用一下。你写的不是机械的模板代码，而是模型本身。