用 dataclass 建模时，经常遇到这种字段：调用方要么传一个值，要么传一组「原材料」让你在构造阶段算出来，而且算出来的结果必须满足某些约束，不满足要立刻报错。比如 price 和 tax_rate 二者必须给其一，另一个由默认税率推导；再比如 birthday 与 age 只能二选一，给了生日就反推年龄，给了年龄就反推生日年份。这类需求用普通 field(default=None) 写，能跑，但类型标注会骗人、__repr__ 会混入不该出现的临时参数、校验逻辑散落在 __init__ 之后，很容易漏。InitVar 正好解决「临时入参」问题，__post_init__ 解决「构造后集中推导与校验」问题，两者配合能把这套逻辑收得非常干净。
先看一个退化写法：默认值 + 事后校验的坑
假设要建一个订单行模型，规则是：unit_price 必填，tax_rate 可选，不传时用 0.13，最终 total 由两者推出，且 total 必须大于 0。
from dataclasses import dataclass
@dataclass
class OrderLine:
sku: str
qty: int
unit_price: float
tax_rate: float = 0.13
total: float = 0.0
def __post_init__(self):
self.total = round(self.unit_price * self.qty * (1 + self.tax_rate), 2)
if self.total <= 0:
raise ValueError("total must be positive")
问题有三处：第一，total 出现在 __init__ 签名里，调用方可以传 OrderLine("A", 1, 10.0, 0.13, 999)，传进去的值会被 __post_init__ 直接覆盖，签名对调用方是误导；第二，repr 里 total=0.0 这种中间态一旦在调试时被看到，会让人怀疑推导没生效；第三，total 的类型是 float，但如果将来想把它做成只读属性，dataclass 的字段机制又不允许。
另一种常见写法是用 Optional 加 None 判断，把 tax_rate 之类的入参从字段列表里「逻辑上」摘出来：
from dataclasses import dataclass
from typing import Optional
@dataclass
class OrderLine:
sku: str
qty: int
unit_price: float
tax_rate: Optional[float] = None
total: float = 0.0
def __post_init__(self):
if self.tax_rate is None:
self.tax_rate = 0.13
self.total = round(self.unit_price * self.qty * (1 + self.tax_rate), 2)
这个版本仍然把 tax_rate 留在字段里，类型标注成了 Optional[float]，可实际上构造结束后它永远是 float。类型检查器（mypy / pyright）无法知道 __post_init__ 之后它已经收窄，调用处还要额外断言。下面用 InitVar 把这个临时入参彻底摘出字段体系。
InitVar 的本质：只进 __init__，不进字段体系
InitVar 是 dataclasses 模块提供的类型标记，声明为 InitVar[T] 的「字段」会参与生成的 __init__ 参数列表，但 不会 成为实例属性，也不会进入 __repr__、__eq__、asdict() 和 fields() 的结果。
from dataclasses import dataclass, InitVar, fields, asdict
@dataclass
class Demo:
name: str
raw_qty: InitVar[str] = "1"
def __post_init__(self, raw_qty):
self.qty = int(raw_qty)
d = Demo("apple", raw_qty="3")
print(d) # Demo(name='apple')
print(asdict(d)) # {'name': 'apple'}
print([f.name for f in fields(d)]) # ['name']
print(d.qty) # 3
运行输出：
Demo(name='apple')
{'name': 'apple'}
['name']
3
三个细节值得记：__post_init__ 的形参必须与 InitVar 声明顺序一致（位置参数逐个传入），名字不必相同但强烈建议相同；InitVar 可以带默认值，但带默认值的 InitVar 后面的普通字段也必须带默认值，否则会触发 TypeError: non-default argument 'xxx' follows default argument；d.qty 之所以能赋值，是因为 dataclass 默认 __eq__ 之外不禁止动态属性，但如果类上加了 slots=True（Python 3.10+），__post_init__ 里给未声明的属性赋值会直接 AttributeError，后文专门讲。
必填与可选的边界
InitVar 本身不表达「必填」，必填与否取决于它有没有默认值。要求「unit_price 和 total_price 至少给一个」，就不能给默认值，而应该把两者都设成无默认的 InitVar，然后在 __post_init__ 里做互斥校验：
from dataclasses import dataclass, InitVar
from typing import Optional
@dataclass
class OrderLine:
sku: str
qty: int
unit_price: InitVar[Optional[float]]
total_price: InitVar[Optional[float]]
tax_rate: float = 0.13
def __post_init__(self, unit_price, total_price):
if (unit_price is None) == (total_price is None):
raise ValueError("exactly one of unit_price / total_price must be provided")
if unit_price is not None:
if unit_price <= 0:
raise ValueError("unit_price must be positive")
self.unit_price = float(unit_price)
self.total_price = round(unit_price * self.qty * (1 + self.tax_rate), 2)
else:
if total_price <= 0:
raise ValueError("total_price must be positive")
self.total_price = float(total_price)
self.unit_price = round(total_price / (self.qty * (1 + self.tax_rate)), 4)
验证：
a = OrderLine("SKU-1", 3, unit_price=10.0)
print(a.unit_price, a.total_price) # 10.0 33.9
b = OrderLine("SKU-1", 3, unit_price=None, total_price=33.9)
print(b.unit_price, b.total_price) # 10.0 33.9
OrderLine("SKU-1", 3, unit_price=None, total_price=None)
最后一行会抛出：
ValueError: exactly one of unit_price / total_price must be provided
注意 InitVar 没有默认值，所以调用时 unit_price 和 total_price 两个关键字都得写，哪怕其中一个传 None。这是刻意的：强制调用方明确表达「我选的是哪一个」。如果嫌啰嗦，可以给两者都加 None 默认值，语义变成「都不传就报错」，对调用方更友好——此时签名里两个参数都有默认值，后续 tax_rate = 0.13 也有默认值，顺序合法。
延迟推导的关键：__post_init__ 里做归一化与不变量校验
__post_init__ 是 dataclass 生成的 __init__ 末尾自动调用的钩子，所有字段（含 InitVar）都被赋值之后才执行，因此它是「构造后、对外可见前」的唯一集中点。把推导逻辑放这里，可以保证实例一旦构造成功，所有不变量（invariant）都成立。
有一点必须理解清楚：__post_init__ 不是「延迟到首次访问时才计算」，它仍然是构造期同步执行的。所谓「延迟推导」，指的是推导发生在入参校验之后、而不是字段默认值表达式中，避免默认值之间互相引用导致 NameError 或顺序依赖。比如下面这种写法是错误的：
from dataclasses import dataclass
@dataclass
class Bad:
qty: int = 1
total: float = qty * 10.0 # NameError: name 'qty' is not defined
类体作用域不会把 qty 暴露给后面的表达式，dataclass 也不做这种依赖解析。正确做法就是把 total 从字段声明里去掉，改成在 __post_init__ 中赋值，或者在 3.8+ 用 field(init=False) 显式声明它不可由调用方传入：
from dataclasses import dataclass, field, InitVar
from typing import Optional
@dataclass
class Invoice:
number: str
qty: int
unit_price: Optional[float] = None
discount: InitVar[float] = 0.0
amount_due: float = field(init=False)
def __post_init__(self, discount):
if self.qty <= 0:
raise ValueError(f"qty must be positive, got {self.qty}")
if self.unit_price is None:
raise ValueError("unit_price is required for Invoice")
if not 0 <= discount < 1:
raise ValueError(f"discount must be in [0, 1), got {discount}")
self.amount_due = round(self.unit_price * self.qty * (1 - discount), 2)
这里同时用了两种机制：discount 用 InitVar，因为它在构造后没有意义、不该出现在 repr 里；amount_due 用 field(init=False)，因为它需要一个类型标注和固定位置，但绝不允许调用方传入。二者结合后，Invoice 的构造签名是 (number, qty, unit_price=None, discount=0.0)，而实例属性只有 number、qty、unit_price、amount_due。
一个高频报错是 field(init=False) 的字段在 __post_init__ 里没赋值就被访问：
AttributeError: 'Invoice' object has no attribute 'amount_due'
原因是 init=False 且没有 default / default_factory 的字段，dataclass 生成的 __init__ 根本不会碰它。只要 __post_init__ 提前 raise 或在某条分支里漏赋值就会踩到。解决办法是给个安全默认值 field(init=False, default=0.0)，或者保证 __post_init__ 的所有代码路径都赋值。
可变默认值：InitVar 挡不住的那类坑
InitVar 如果默认值是可变对象，同样会触发 dataclass 的可变默认值限制：
ValueError: mutable default <class 'list'> for field tags is not allowed: use default_factory
即便它是 InitVar 也一样，因为限制发生在字段解析阶段。正确写法：
from dataclasses import dataclass, field, InitVar
@dataclass
class Tagged:
name: str
tags: InitVar[list] = field(default_factory=list)
def __post_init__(self, tags):
self._tags = list(tags) # 复制一份，避免外部列表被后续修改影响
注意 __post_init__ 里必须 list(tags) 做浅拷贝，否则调用方传入的列表后续被 append，实例内部状态会跟着变，这类 bug 极难排查。
继承链上的执行顺序与 signature 约束
当子类继承带 InitVar 的父类时，子类的 __post_init__ 需要手动调用 super().__post_init__()，dataclass 不会自动级联。如果父类 __post_init__ 需要 InitVar 参数，子类也得把这个参数声明进自己的 __post_init__ 签名并透传：
from dataclasses import dataclass, InitVar
@dataclass
class Base:
name: str
weight_kg: InitVar[float] = 0.0
def __post_init__(self, weight_kg):
if weight_kg < 0:
raise ValueError("weight_kg must be non-negative")
self.weight_kg = weight_kg
@dataclass
class Package(Base):
length_cm: float = 0.0
def __post_init__(self, weight_kg):
super().__post_init__(weight_kg)
if self.length_cm < 0:
raise ValueError("length_cm must be non-negative")
如果子类忘了写 def __post_init__(self, weight_kg) 而写成无参版本，运行时会得到：
TypeError: Package.__post_init__() takes 1 positional argument but 2 were given
反过来，子类 __post_init__ 声明了父类没有的 InitVar 参数，同样会报参数数量不匹配。排查方法很简单，打印一下生成的签名：
import inspect
print(inspect.signature(Package))
print(inspect.signature(Package.__post_init__))
(name: str, weight_kg: float = 0.0, length_cm: float = 0.0) -> None
(self, weight_kg) -> None
另外，字段顺序在继承时也是先父后子，所以子类不能给父类已有的非默认字段追加无默认字段的顺序冲突——如果父类最后一个字段有默认值，子类新增无默认字段会直接抛出那个熟悉的 TypeError: non-default argument 'xxx' follows default argument。这类问题在 dataclass 继承里极其常见，处理方式是父类不要留带默认值的字段，或者子类新增字段也一律带默认值。
slots 与 frozen：两个会改变行为的开关
Python 3.10 起 @dataclass(slots=True) 会为类生成 __slots__，实例不能再挂任意属性。此时 __post_init__ 里赋值的属性必须在类体里声明过，否则报错：
from dataclasses import dataclass, InitVar
@dataclass(slots=True)
class P:
name: str
parts: InitVar[list]
def __post_init__(self, parts):
self.parts = parts # 这里能成功，因为 'parts' 不是 slot 名？
p = P("a", [1, 2])
实际运行：
AttributeError: 'P' object has no attribute 'parts'
原因正是 InitVar 不产生 slot，而 slots=True 后实例没有 __dict__，动态属性无处安放。修法有两种：把结果存到声明过的普通字段上，或者声明一个不含 InitVar 的普通字段承接结果：
from dataclasses import dataclass, InitVar, field
@dataclass(slots=True)
class P:
name: str
parts: InitVar[list]
_parts: tuple = field(init=False, default=())
def __post_init__(self, parts):
self._parts = tuple(parts)
print(P("a", [1, 2])) # P(name='a')
frozen=True 的情况更微妙：整个实例在 __post_init__ 期间仍可写（dataclass 用 object.__setattr__ 绕过冻结），所以给「通过 InitVar 推导出来的普通字段」赋值是允许的；但给 InitVar 同名属性赋值会报 FrozenInstanceError，因为 InitVar 压根不是字段，走的是普通 setattr。
from dataclasses import dataclass, InitVar, field
@dataclass(frozen=True)
class Money:
cents: int
yuan: InitVar[float] = 0.0
note: str = field(init=False, default="")
def __post_init__(self, yuan):
if self.cents < 0 and yuan <= 0:
raise ValueError("provide positive cents or yuan")
object.__setattr__(self, "note", f"{self.cents}c / {yuan}y")
m = Money(cents=1250)
print(m)
print(m.note)
输出：
Money(cents=1250)
1250c / 0.0y
注意 note 是 init=False 的普通字段，在 frozen=True 下也需要 object.__setattr__，直接 self.note = ... 会抛 dataclasses.FrozenInstanceError: cannot assign to field 'note'。这是 frozen 模型下 __post_init__ 推导字段的标准写法。
工程实践：把校验、推导、错误信息组织好
真实项目里，推荐把 __post_init__ 拆成「收敛入参 → 校验 → 推导 → 注册」四段，且错误信息带上字段名和非法值，便于日志检索。下面是一个可直接运行的完整示例，覆盖必填判断、互斥、范围校验与格式化推导：
from __future__ import annotations
from dataclasses import dataclass, field, InitVar
from datetime import date, datetime
from typing import Optional
@dataclass
class Subscription:
user_id: str
start: date
months: InitVar[Optional[int]] = None
end: InitVar[Optional[date]] = None
plan: str = "basic"
valid_until: date = field(init=False)
display: str = field(init=False, default="")
def __post_init__(self, months, end):
if (months is None) == (end is None):
raise ValueError(
"exactly one of months / end must be provided, "
f"got months={months!r}, end={end!r}"
)
if self.plan not in {"basic", "pro", "enterprise"}:
raise ValueError(f"unknown plan {self.plan!r}")
if months is not None:
if not isinstance(months, int) or months <= 0:
raise ValueError(f"months must be a positive int, got {months!r}")
if months > 36:
raise ValueError(f"months exceeds limit 36, got {months}")
year, month = self.start.year, self.start.month + months
year += (month - 1) // 12
month = (month - 1) % 12 + 1
day = min(self.start.day, 28)
self.valid_until = date(year, month, day)
else:
if not isinstance(end, date):
raise TypeError(f"end must be datetime.date, got {type(end).__name__}")
if end <= self.start:
raise ValueError(f"end {end} must be after start {self.start}")
self.valid_until = end
self.display = (
f"{self.user_id}@{self.plan} "
f"[{self.start.isoformat()} -> {self.valid_until.isoformat()}]"
)
s1 = Subscription("u001", date(2024, 1, 31), months=3)
print(s1.valid_until, "|", s1.display)
s2 = Subscription("u002", date(2024, 3, 1), end=date(2024, 12, 31), plan="pro")
print(s2.valid_until, "|", s2.display)
输出：
2024-04-28 | u001@basic [2024-01-31 -> 2024-04-28]
2024-12-31 | u002@pro [2024-03-01 -> 2024-12-31]
几个可复用的经验：
- 互斥判断用
(a is None) == (b is None)，比if a is None and b is None / elif a is not None and b is not None少两个分支，也不容易漏。 - 错误信息里同时打印
!r的原始值，months='3'这种字符串误传能一眼看出来；!r在str场景比直接插值更有诊断价值。 - 类型校验（
isinstance）优先用TypeError，取值范围用ValueError，方便上层按异常类型分流。 - 所有对外可见的派生字段用
field(init=False)声明，既保证类型标注可被 mypy 识别，又保证调用方传不进来。 - 需要一个「只读计算属性」时，优先
@property而不是在__post_init__里算一次存下来，除非计算很重或结果依赖构造时的中间入参。上面display属于后者（依赖months这种InitVar），存下来是合理的。
何时不该用 InitVar
InitVar 不是万能的。若临时参数在构造之后仍有调试价值，或者需要参与 __eq__、序列化，就不要用 InitVar，改成普通字段 + __post_init__ 归一化更合适。另一个反面场景是 replace()：dataclasses.replace(obj, ...) 会重新调用 __init__，而 InitVar 的当前值不会自动带过去，必须显式传：
from dataclasses import replace
s3 = replace(s1, plan="pro", months=12)
print(s3.valid_until) # 2025-01-28
如果漏传 months 且 end 也没传，会得到前面那条 ValueError: exactly one of months / end must be provided。这在批量改写配置对象时是个常见陷阱，写代码时最好在 replace 处加注释说明必须回填哪个 InitVar。
JSON 反序列化场景
从外部 JSON 构造这类对象时，InitVar 恰好是很好的防线：外部只允许给「原始入参」，派生字段调用方传了也会因为 init=False 直接抛 TypeError: __init__() got an unexpected keyword argument 'valid_until'。配合一个显式白名单过滤即可：
import json
import inspect
ALLOWED = set(inspect.signature(Subscription).parameters)
def from_json(payload: str) -> Subscription:
data = json.loads(payload)
extra = set(data) - ALLOWED
if extra:
raise ValueError(f"unexpected keys: {sorted(extra)}")
if "start" in data:
data["start"] = datetime.fromisoformat(data["start"]).date()
if "end" in data and data["end"]:
data["end"] = datetime.fromisoformat(data["end"]).date()
return Subscription(**data)
obj = from_json('{"user_id": "u9", "start": "2024-06-01", "months": 6, "plan": "pro"}')
print(obj.display)
输出 u9@pro [2024-06-01 -> 2024-12-01]。注意 inspect.signature 会把 InitVar 参数算进去，这正是我们要的，因为它就是允许外部输入的键集合。
小结
把「临时入参」和「派生结果」分开，是 dataclass 建模里最值得坚持的一条纪律：InitVar 负责让临时入参只出现在 __init__ 签名里、不进 repr / __eq__ / asdict()；__post_init__ 负责在全部赋值完成后做互斥校验、范围校验和派生字段推导；派生字段用 field(init=False) 声明，保证调用方无法伪造。三者组合后，构造签名即协议、构造成功即不变量成立，类型检查器和序列化都能正常工作。涉及继承时记得手动调用 super().__post_init__() 并对齐 InitVar 参数；涉及 slots=True 或 frozen=True 时注意派生属性必须先声明、并视情况使用 object.__setattr__。
FAQ
Q1：__post_init__ 里抛异常，对象会不会被创建出来？
不会。dataclass 生成的 __init__ 末尾调用 __post_init__，异常会中断 __init__，实例引用不会返回给调用方，垃圾回收后即清理。但若在 __post_init__ 里已经做了副作用（写文件、注册到全局字典），必须自己回滚，dataclass 不提供钩子。
Q2：为什么 InitVar 参数在 __post_init__ 里传的是位置参数，我写关键字行不行？
不行。生成的调用是 self.__post_init__(field1, field2) 这种按声明顺序的位置调用。所以 __post_init__ 的形参名可以任意，但顺序必须与 InitVar 声明顺序一致，否则值会错位。建议直接同名，避免歧义。
Q3：报 TypeError: non-default argument 'x' follows default argument 怎么排查？
检查字段声明顺序，dataclass 要求有默认值的字段不能出现在无默认值字段之前，InitVar 也参与这个规则。继承场景下先父类后子类排序，父类最后一个字段有默认值时，子类新增无默认字段必然报错。解决办法：给子类字段加默认值，或用 field(init=False) 从 __init__ 中移出。
Q4：slots=True 下 __post_init__ 写 self.xxx = 报 AttributeError 怎么办？
因为 xxx 没有在类体里被声明为字段或 slot。InitVar 不产生 slot，所以不能给 InitVar 同名属性赋值。要么把结果写到声明过的普通字段（推荐 field(init=False)），要么显式在类体加 __slots__ = ("xxx",)，但后者会与 dataclass 自动生成的 slot 冲突，不推荐。
Q5：frozen=True 时 __post_init__ 能不能给字段赋值？
能，但仅限「通过 InitVar 推导出的普通字段」且建议用 object.__setattr__(self, "field", value)。直接 self.field = value 会抛 dataclasses.FrozenInstanceError。给 InitVar 同名属性赋值则一定失败，因为它不是字段。
Q6：asdict() / astuple() 会包含 InitVar 吗？
不会。InitVar 不在 fields() 列表中，asdict() 只递归处理真实字段。这也是把敏感入参（比如明文密码）声明为 InitVar 并只保留哈希值字段的一个实用技巧。