如何在 attrs 类中正确使用类变量（ClassVar）-Python教程-PHP中文网

如何在 attrs 类中正确使用类变量（ClassVar）

attrs 库默认忽略 typing.ClassVar 注解的字段，因此无法通过 @define 自动生成类变量；需采用继承混入类或类定义后动态赋值的方式显式声明类变量。

`attrs` 库默认忽略 `typing.classvar` 注解的字段，因此无法通过 `@define` 自动生成类变量；需采用继承混入类或类定义后动态赋值的方式显式声明类变量。

在使用 attrs 构建数据类时，其核心优势在于通过类型注解和 field() 自动管理实例属性，大幅提升代码简洁性与可维护性。然而，attrs 明确不支持将 typing.ClassVar 作为字段处理——正如官方文档所强调：“标注为 ClassVar 的属性，以及未标注也未显式调用 field() 的变量，均会被 attrs 忽略”。这意味着以下写法不会生效：

from typing import ClassVar
from attrs import define

@define
class Person:
    name: str
    my_class_var: ClassVar[str] = "shared"  # ❌ 被 attrs 忽略，实例/类上均不可访问

p = Person("Alice")
# AttributeError: 'Person' object has no attribute 'my_class_var'

要正确定义并使用类变量，推荐以下两种可靠且符合 Python 惯例的方式：

✅ 方式一：通过混入（Mixin）类继承

将类变量定义在独立基类中，再让 @define 类继承该基类。这是最清晰、可复用性强、语义明确的做法：

from attrs import define, field

class SharedConfig:
    VERSION: str = "2.1.0"
    DEFAULT_TIMEOUT: int = 30

@define
class APIRequest(SharedConfig):  # 继承获得类变量
    url: str = field()
    method: str = field(default="GET")

print(APIRequest.VERSION)           # → "2.1.0"
print(APIRequest.DEFAULT_TIMEOUT)   # → 30
req = APIRequest("https://api.example.com")
print(req.VERSION)  # 同样可从实例访问（因类变量可通过实例读取）

✅ 方式二：类定义后动态赋值

适用于简单场景或需运行时计算类变量值的情况：

from attrs import define, field

@define
class Logger:
    name: str

# 动态添加类变量（推荐在模块级定义后立即赋值，避免隐式副作用）
Logger.LOG_LEVEL = "INFO"
Logger.FORMAT = "%(asctime)s - %(name)s - %(levelname)s"

print(Logger.LOG_LEVEL)  # → "INFO"
l = Logger("main")
print(l.FORMAT)          # → "%(asctime)s - %(name)s - %(levelname)s"

⚠️ 注意事项

不要混淆 ClassVar 与 field(default=...)：后者创建的是所有实例共享的默认值（仍属实例字段），而非真正的类变量；修改该字段会影响单个实例，而非整个类。
类变量不可被 attrs 自动生成 __init__ 参数：ClassVar 字段绝不会出现在 __init__ 签名中，也不参与 repr、eq 或 hash 计算——这正是其设计本意。
优先选择 Mixin 方式：它更利于类型检查器（如 mypy）识别、支持 IDE 自动补全，且便于多类复用同一组配置。