一、注解概述

@dataclass

dataclass 是 Python 3.7 及以上版本中引入的标准库装饰器，位于 dataclasses 模块（

dataclasses

在传统方式下，若要手动实现一个功能完整的数据类，开发者需要自行编写诸如 __init__（

__init__

__repr__

__eq__

核心特性包括：

• 自动创建构造函数 __init__（

  __init__

  ）
• 自动生成可读性强的字符串表示 __repr__（

  __repr__

  ）
• 实现基于所有字段的相等性比较 __eq__（

  __eq__

  ）
• 可选地生成排序相关方法，如 __lt__（

  __lt__

  ）、__gt__（

  __gt__

  ）等
• 支持字段默认值、类型注解以及细粒度的字段行为定制

二、基础使用示例

1. 最简使用案例

from dataclasses import dataclass

@dataclass
class Person:
    name: str
    age: int
    city: str = "Beijing"  # 带默认值的字段

# 自动生成 __init__ 方法，可直接实例化对象
p1 = Person("Alice", 25)
p2 = Person("Bob", 30, "Shanghai")

# 自动生成 __repr__ 方法，输出格式清晰
print(p1)  # 输出：Person(name='Alice', age=25, city='Beijing')

# 自动生成 __eq__ 方法，支持实例间相等判断
print(p1 == Person("Alice", 25))  # True
print(p1 == p2)  # False

2. 与传统类定义对比

如果不使用 dataclass（

@dataclass

class Person:
    def __init__(self, name: str, age: int, city: str = "Beijing"):
        self.name = name
        self.age = age
        self.city = city

    def __repr__(self):
        return f"Person(name='{self.name}', age={self.age}, city='{self.city}')"

    def __eq__(self, other):
        if not isinstance(other, Person):
            return False
        return (self.name == other.name and 
                self.age == other.age and 
                self.city == other.city)

可以看出，手动实现不仅代码量大，而且容易出错，维护成本高。

三、关键参数与高级定制

dataclass 装饰器提供多个布尔型参数，用于控制自动生成哪些特殊方法，灵活适应不同场景需求。

init

__init__

repr

__repr__

eq

__eq__

order

__lt__

__gt__

frozen

slots

__slots__

1. 启用排序功能（order=True）

order=True

通过设置 order=True，可以为类启用自然排序能力，字段按声明顺序依次比较：

@dataclass(order=True)
class Student:
    score: int
    name: str

s1 = Student(90, "Alice")
s2 = Student(85, "Bob")
print(s1 > s2)  # 输出：True（先按 score 比较，score 不同则无需比较 name）

2. 冻结实例（frozen=True）

frozen=True

当设置 frozen=True 时，实例的所有属性变为只读，任何赋值操作都会引发异常：

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

p = Point(1, 2)
p.x = 3  # 抛出 dataclasses.FrozenInstanceError: cannot assign to field 'x' 
FrozenInstanceError

3. 禁用构造方法生成（init=False）

init=False

适用于需要完全自定义初始化逻辑的情况：

@dataclass(init=False)
class Product:
    id: int
    name: str

    def __init__(self, id: int):
        self.id = id
        self.name = f"Product-{id}"

p = Product(1001)
print(p)  # 输出：Product(id=1001, name='Product-1001')

四、field() 函数 —— 实现字段级精细控制

field

为了对单个字段的行为进行更细致的定制，dataclasses 提供了 field() 函数（

dataclasses.field()

常用参数包括（

default

default_factory

• default：字段的默认值
• default_factory：用于生成默认值的可调用对象，适合可变类型（如 list、dict）
• init：该字段是否包含在生成的 __init__ 中
• repr：该字段是否包含在 __repr__ 输出中
• compare：该字段是否参与 __eq__ 和 order 比较
• hash：是否在计算哈希时使用该字段

1. 可变默认值（

default_factory

在 Python 中，直接使用可变对象（例如

[]

{}

from dataclasses import dataclass, field

@dataclass
class Group:
    name: str
    members: list[str] = field(default_factory=list)  # 正确方式
    # 错误示例：members: list[str] = [] （会导致所有实例共用同一列表）

g1 = Group("Team A")
g1.members.append("Alice")

g2 = Group("Team B")
print(g1.members)  # 输出：['Alice']
print(g2.members)  # 输出：[]（互不影响）

2. 排除字段在

__init__

__repr__

通过设置 repr=False 或 init=False，可以控制字段是否出现在字符串表示或构造函数中：

@dataclass
class User:
    name: str
    password: str = field(repr=False, init=False)  # 不参与 __repr__，也不进入 __init__

u = User("Alice")
u.password = "123456"
print(u)  # 输出：User(name='Alice')（password 被隐藏）

3. 字段不参与比较

当使用 order=True 时，可通过 compare=False 排除某些字段在排序和相等性判断中的影响：

@dataclass(order=True)
class Book:
    title: str
    isbn: str = field(compare=False)  # 不参与排序与 == 比较

b1 = Book("Python Guide", "978-0123456789")
b2 = Book("Python Guide", "978-9876543210")
print(b1 == b2)  # 输出：True（仅比较 title，isbn 被忽略）

default_factory

init

__init__

repr

__repr__

compare

__eq__

hash

__hash__

metadata

五、其他实用方法

asdict()

astuple()

利用 asdict() 和 astuple() 可将数据类实例快速转为标准数据结构：

from dataclasses import dataclass, asdict, astuple

@dataclass
class Point:
    x: int
    y: int

p = Point(1, 2)
print(asdict(p))   # 输出：{'x': 1, 'y': 2}
print(astuple(p))  # 输出：(1, 2)

replace()

使用 replace() 函数基于已有实例生成新对象，并可更新指定字段：

from dataclasses import dataclass, replace

@dataclass
class Car:
    brand: str
    color: str = "black"

c1 = Car("Toyota")
c2 = replace(c1, color="white")  # 基于 c1 创建新实例，仅修改 color
print(c2)  # 输出：Car(brand='Toyota', color='white')

六、注意事项

版本要求

@dataclass

dataclasses

pip install dataclasses

类型注解

所有字段必须带有类型注解（包括

Any

@dataclass

继承机制

数据类支持继承，子类会自动合并父类定义的字段，且父类字段排在前面：

@dataclass
class Parent:
    a: int

@dataclass
class Child(Parent):
    b: str

c = Child(1, "hello")  # 参数顺序：a 对应 1，b 对应 "hello"

__hash__

• 若设置了

  eq=True

  且

  frozen=True

  ：自动生成

  __hash__

  。
• 若设置了

  eq=True

  但

  frozen=False

  ：则不生成哈希函数，实例不可哈希（

  __hash__ = None

  ）。
• 若未设置

  eq=False

  ：采用默认的

  __hash__

  行为（基于对象内存标识进行比较）。

七、适用场景

• 数据传输对象（DTO）：适用于 API 接口返回的数据模型定义。
• 配置类：用于封装程序运行所需的配置参数。
• 简单数据容器：如解析数据库记录、CSV 文件结果等场景。
• 替代

  collections.namedtuple

  ：

  @dataclass

  提供更强灵活性，支持可变属性、复杂默认值、类继承等功能。

@dataclass

作为 Python 开发中处理数据容器的首选方案，它能够有效简化数据类的定义过程。通过自动生成功能，减少大量重复性的样板代码，显著提升开发效率。同时，该工具还具备高度灵活的定制化配置能力，满足多样化的需求场景。