Python dataclass ClassVar 怎样排除类级配置字段

在 @dataclass 中，如果一个配置只属于类本身，不应该成为每个实例的初始化参数或序列化字段，可以把它标注为 typing.ClassVar。例如把重试开关写成 retryable: ClassVar[bool] = True，dataclasses 会忽略它；真正的实例数据仍然使用普通类型标注。

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

普通类型标注为什么会变成 dataclass 字段

@dataclass 会读取类体里的类型标注，并据此组织生成的 __init__()、__repr__()、比较方法和 fields() 结果。下面的 timeout 和 retryable 都是普通标注，所以它们都会被当成实例字段：

from dataclasses import dataclass

@dataclass
class RequestPolicy:
    # 普通标注会进入生成的 __init__ 参数
    timeout: int = 30
    # 这个开关也会被视为每个实例自己的字段
    retryable: bool = True

policy = RequestPolicy(timeout=10, retryable=False)
print(policy)

如果这个类的设计要求每个实例都能拥有不同的 retryable，上面的写法是合理的。问题出现在它实际上是全类共用的策略时：调用方会误以为它需要在构造对象时传入，asdict() 也会把它当成业务数据。

用 ClassVar 排除类级配置字段

把类型改成 ClassVar[T] 即可表达“这是类变量，不是 dataclass 字段”。ClassVar 来自 typing，方括号里的类型只描述这个类属性的值类型：

from dataclasses import dataclass
from typing import ClassVar

@dataclass
class RequestPolicy:
    # 只参与实例初始化和实例状态管理
    timeout: int = 30
    # 类级开关不会进入生成的 __init__
    retryable: ClassVar[bool] = True

policy = RequestPolicy(timeout=10)
print(policy.timeout)
print(RequestPolicy.retryable)

此时生成的构造方法只需要 timeout。类属性仍然可以通过 RequestPolicy.retryable 读取；通过实例访问时，Python 也会沿着属性查找规则读到类上的值，但它不代表每个实例都拥有一份独立字段。

fields() 和 asdict() 怎样确认识别结果

排除是否生效，不要只看对象能不能访问这个属性，应该分别检查字段元数据和序列化结果。fields() 不会返回 ClassVar 伪字段，asdict() 也只处理真正的 dataclass 字段：

from dataclasses import asdict, dataclass, fields
from typing import ClassVar

@dataclass
class RequestPolicy:
    # 这个字段会出现在 fields() 和 asdict() 中
    timeout: int = 30
    # 这个配置只保留在类上，不进入字段集合
    retryable: ClassVar[bool] = True

field_names = [item.name for item in fields(RequestPolicy)]
payload = asdict(RequestPolicy(timeout=10))

print(field_names)
print(payload)

预期的结构是：

['timeout']
{'timeout': 10}

这里的两个结果分别回答了两个常见问题：生成的 dataclass 字段集合只有 timeout；把实例转成字典时，类级的 retryable 不会混入数据。如果业务确实需要把这个类级开关写入配置输出，应当在序列化层显式添加，而不是把它误标为实例字段。

默认值、继承和可变配置的三个边界

第一，ClassVar 不等于常量，也不会自动禁止重新赋值。它主要是类型标注和 dataclass 字段识别信号；如果配置必须不可变，仍需要通过模块约定、属性封装或其他设计保证。

第二，继承时要看最终类上的注解和 dataclass 字段规则。父类的 ClassVar 不会因为被继承就突然变成子类实例字段，但子类如果重新用普通标注声明同名属性，就改变了子类自己的字段含义，应该避免让同一个名字在继承层级中语义漂移。

第三，不要把可变对象随意放在共享的 ClassVar 中：

from dataclasses import dataclass
from typing import ClassVar

@dataclass
class Registry:
    # 所有实例共享同一个字典，修改会影响整个类
    handlers: ClassVar[dict[str, str]] = {}

    def add_handler(self, name: str, target: str) -> None:
        # 这里修改的是类级共享状态，不是当前实例的字段
        type(self).handlers[name] = target

如果共享注册表正是设计目标，可以明确写在类级文档和方法命名中；如果每个对象都应该有独立容器，则应改成普通字段并用 field(default_factory=dict) 创建实例级字典。

一张表记住该怎么选

相关问题

ClassVar 会出现在 __init__ 参数里吗？

不会。dataclass 会把它排除出字段处理，因此不会为它生成初始化参数。

为什么实例还能访问 ClassVar？

因为这是 Python 的类属性查找行为，不代表它被 dataclass 当成实例字段保存。

ClassVar 能替代 field(init=False) 吗？

不能简单互换。field(init=False) 仍然是实例字段，只是禁止通过生成的构造方法传入；ClassVar 则从 dataclass 字段集合中排除，二者的存储语义不同。

判断标准可以收束成一句话：需要随对象创建、比较或序列化的数据，用普通字段；只属于类并由所有实例共享的配置，使用 ClassVar，再用 fields() 和 asdict() 确认结果。