Python 深入浅出：用内置 dataclasses 优雅声明数据结构

在编写应用程序时，我们经常需要创建一些纯粹的“数据容器类”（如配置项、API 传输实体 DTO、数据库记录映射等）。它们的核心作用是存储数据，而不包含复杂的业务行为。

在 Python 3.7 之前，为了让这类数据对象具备基本的功能（如方便地打印、支持比较大小、支持作为字典的 Key），我们不得不手写大量冗长的样板代码：__init__、__repr__、__eq__、__hash__ 等。

为了终结这些枯燥无味的复读机代码，Python 3.7 引入了 dataclasses（数据类，定义在 PEP 557 中） 模块。

本文将带您剖析 dataclasses 的底层黑魔法，掌握优雅声明与管理数据对象的高级实战技巧。

一、 传统数据类的繁琐与痛点

假设我们想声明一个包含商品名称、价格和标签的普通数据类：

class Product:
    def __init__(self, name: str, price: float, tags: list):
        self.name = name
        self.price = price
        self.tags = tags

    def __repr__(self):
        # 为了调试时能清晰打印类内容，必须手写 repr
        return f"Product(name={self.name!r}, price={self.price}, tags={self.tags})"

    def __eq__(self, other):
        # 为了支持 == 比较，必须手写 eq
        if not isinstance(other, Product):
            return NotImplemented
        return self.name == other.name and self.price == other.price

为了存储 3 个属性，我们写了将近 15 行的样板代码！

二、 现代化声明：@dataclass 装饰器

使用 @dataclass 装饰器后，上面的冗长代码可以瞬间缩减为：

from dataclasses import dataclass

@dataclass
class Product:
    name: str
    price: float
    tags: list

在后台，Python 解释器会自动根据你声明的类型注解，为你自动生成 __init__、__repr__、__eq__ 等所有方法。

三、 dataclasses 核心高阶特性

除了自动生成样板代码，dataclasses 还内置了非常强大的高级参数与校验机制：

1. 规避“可变默认参数（Mutable Defaults）”陷阱

在 Python 中，如果直接写 tags: list = [] 作为默认参数，会导致所有实例共享同一个列表的经典 Bug。数据类对此进行了严格限制，要求必须使用 field 函数的 default_factory 来声明可变类型的默认值：

from dataclasses import dataclass, field

@dataclass
class Product:
    name: str
    price: float
    # 使用 default_factory 声明每个实例独享一个独立的空列表
    tags: list[str] = field(default_factory=list)

2. 声明只读与可哈希对象（frozen=True）

如果你希望创建的数据对象在初始化后不可被修改（Immutable），可以开启 frozen=True。这还会自动为类生成 __hash__ 方法，使其可以安全地作为字典的键（Key）或塞入集合（Set）中：

@dataclass(frozen=True)
class UserConfig:
    user_id: int
    theme: str = "dark"

3. 初始化后校验与属性加工（__post_init__）

数据类会自动帮我们生成 __init__。如果我们想在实例化时进行参数校验，或者根据传入的属性动态计算出一个新属性，可以使用 __post_init__ 钩子函数：

@dataclass
class Invoice:
    item: str
    price: float
    quantity: int
    total_cost: float = field(init=False)  # 声明 total_cost 不需要通过 __init__ 传入

    def __post_init__(self):
        # 1. 参数校验
        if self.price < 0 or self.quantity <= 0:
            raise ValueError("价格或数量不能为负数")
        # 2. 属性动态计算
        self.total_cost = self.price * self.quantity

四、 总结

1. 全面替换旧写法：在新版 Python 中，只要是声明纯数据容器类，优先使用 @dataclass，彻底废弃繁琐的手写 __init__ 写法。
2. 轻量与灵活性：数据类只关注代码生成，不影响运行性能（它生成的代码与手写的原生代码速度完全一样）。
3. 与 Pydantic 的分工：
4. 如果只是在项目内部进行简单的数据存储与传递，首选内置的 dataclasses；
5. 如果需要处理复杂的外部 API 边界数据校验与强制类型转换，首选 Pydantic。

利用 @dataclass 装饰器，精简您的代码行数，写出更现代、更干净的 Python 数据结构吧！