Python dataclass __post_init__ 计算派生字段

Python 的 dataclass 适合把“外部传入的原始字段”和“由原始字段计算出的结果”放进同一个数据模型。最小做法是：原始字段保持普通声明，派生字段使用 field(init=False) 排除出构造器，再在 __post_init__ 中计算。这样调用者只需要提供事实数据，模型在生成的 __init__ 完成赋值后统一得到派生结果。

官方文档：https://docs.python.org/3/library/dataclasses.html

如果一个字段能由其他字段确定，就不要让调用者重复传入它；让生成的 __init__ 先保存输入，再由 __post_init__ 计算一次，是最清晰的 dataclass 建模边界。

从重复传值到集中计算

在订单、价格、指标或配置模型里，最容易失控的做法是同时接收 base_price 和 payable。调用者既要传原始值，又要保证计算值没有过期，数据类就失去了约束作用。规模变大后，多个调用入口会把相同规则分散到构造器、工厂函数和更新逻辑里，最终出现“对象能创建，但字段互相矛盾”的问题。

更稳的边界是让构造器只接受原始输入。例如单价、数量和折扣是输入，合计金额是派生值。__post_init__ 正好位于生成的 __init__ 之后：此时普通字段已经写入实例，派生字段可以安全读取它们。

让 __post_init__ 接住生成的 __init__

下面的类没有手写 __init__。@dataclass 会根据带类型注解的字段生成构造方法，而 total 用 init=False 表示它不应该出现在构造参数里。

from dataclasses import dataclass, field

@dataclass
class LineItem:
    name: str
    price: float
    quantity: int = 1
    total: float = field(init=False)

    def __post_init__(self) -> None:
        # 生成的 __init__ 已经完成 price 和 quantity 的赋值。
        self.total = self.price * self.quantity

item = LineItem(name="键盘", price=299.0, quantity=2)
print(item.total)  # 598.0

这个设计有两个直接收益：调用方不能在构造时手动覆盖 total，并且计算规则集中在模型自己的生命周期里。若 total 依赖更多字段，只需要在同一个方法中明确写出依赖关系。

把只在构造阶段需要的值交给 InitVar

有些参数只用于初始化过程，并不应该成为对象的持久字段。例如折扣规则来自外部配置，模型只需要拿它计算 payable，不必把整份规则对象保存下来。这时可以使用 InitVar。它会进入生成的 __init__，随后按声明顺序传给 __post_init__，但不会作为普通数据类字段返回。

from dataclasses import InitVar, dataclass, field

@dataclass
class Invoice:
    subtotal: float
    discount_rate: InitVar[float] = 0.0
    payable: float = field(init=False)

    def __post_init__(self, discount_rate: float) -> None:
        # discount_rate 只参与本次构造，不作为实例字段保存。
        rate = min(max(discount_rate, 0.0), 1.0)
        self.payable = round(self.subtotal * (1 - rate), 2)

invoice = Invoice(100.0, discount_rate=0.15)
print(invoice.payable)  # 85.0

如果外部参数需要在对象创建后反复使用，就不要把它误写成 InitVar；应该声明为普通字段。InitVar 适合“构造时注入、计算后释放”的依赖。

继承时补上基类初始化

数据类生成的 __init__ 不会自动调用一个普通基类的 __init__。如果子类继承了非 dataclass 基类，就可以在 __post_init__ 中显式衔接。若基类本身也是 dataclass，派生数据类会按字段顺序合并它的字段，通常不需要手动调用基类构造器。

from dataclasses import dataclass

class NamedEntity:
    def __init__(self, label: str) -> None:
        # 普通基类的状态不会被 dataclass 自动初始化。
        self.label = label

@dataclass
class Product(NamedEntity):
    label: str
    price: float

    def __post_init__(self) -> None:
        # 显式把已经由 dataclass 赋值的字段交给基类处理。
        super().__init__(self.label)
        self.display = f"{self.label} / {self.price:.2f}"

product = Product("鼠标", 79.0)
print(product.display)

继承层次越深，越要把“哪个类负责哪个字段”写清楚。否则同名字段、默认值和基类副作用会让派生字段的计算顺序变得难以追踪。

明确更新和 frozen 的运行边界

__post_init__ 只发生在生成的构造流程中。它不是响应式监听器：对象创建后修改 price，total 不会自动重新计算。如果模型允许修改原始字段，应把更新动作封装成方法，并在方法里重新计算所有受影响的派生值。

from dataclasses import dataclass, field

@dataclass
class CartLine:
    price: float
    quantity: int
    total: float = field(init=False)

    def __post_init__(self) -> None:
        # 构造完成时建立第一次派生值。
        self._recalculate()

    def change_quantity(self, quantity: int) -> None:
        # 通过领域方法修改输入，避免遗漏派生值同步。
        if quantity  None:
        # 把同一条计算规则集中到一个私有方法。
        self.total = self.price * self.quantity

line = CartLine(12.5, 4)
line.change_quantity(6)
print(line.total)  # 75.0

如果对象应该近似不可变，可以使用 @dataclass(frozen=True)。这会让字段赋值触发异常，适合值对象或需要稳定哈希的模型；但它并不会让对象变成绝对不可变，也不应通过绕过机制随意修改派生字段。

用 replace 重新计算派生字段

对可变模型，更新方法通常更直观；对值对象，则可以用 dataclasses.replace 创建一个新实例。官方实现会通过数据类的 __init__ 创建新对象，因此存在 __post_init__ 时会再次执行，派生字段也会随新输入重算。

from dataclasses import dataclass, field, replace

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

    def __post_init__(self) -> None:
        # frozen 实例需要通过 object.__setattr__ 写入派生字段。
        object.__setattr__(self, "area", self.width * self.height)

small = Rectangle(3, 4)
large = replace(small, width=5)
print(small.area)  # 12
print(large.area)  # 20

需要注意的是，replace 不是对原对象做局部复制后强行覆盖；它会重新走构造流程。对于 init=False 字段，不要把它放到 replace 的变更参数里，而应让 __post_init__ 根据新的输入重新计算。

一份可复用的模型检查清单

排查 dataclass 派生字段时，可以按“字段是否进入构造器、生成的 __init__ 是否存在、__post_init__ 是否被调用、派生值是否需要持续同步”四个问题定位。不要只看到字段有默认值就认为它会自动刷新。

常见问题

为什么写了 __post_init__ 却没有执行？

如果类关闭了生成的 __init__，或者自己实现了 __init__ 却没有显式调用 __post_init__，它就不会自动触发。先确认初始化入口仍由 dataclass 管理。

派生字段应该写默认值吗？

通常不需要。使用 field(init=False) 声明它由初始化后逻辑负责写入，可以更早暴露遗漏计算的问题。

修改原始字段后怎么自动更新？

普通 dataclass 不提供属性级响应式同步。将修改封装进领域方法，或改用不可变对象配合 replace，比在多个属性 setter 中复制计算规则更易维护。

总结来说，__post_init__ 的价值不是替代所有业务方法，而是把“对象刚完成初始化时必须成立的派生约束”集中表达出来。把输入字段、构造期依赖和派生字段分层，数据模型才会在规模扩大后仍然容易理解和演进。