attrs 库默认忽略 typing.ClassVar 注解的字段，不将其转为实例属性；若需类变量，应通过继承混入类或直接在类对象上赋值实现，而非依赖字段注解。
`attrs` 库默认忽略 `typing.classvar` 注解的字段，不将其转为实例属性；若需类变量，应通过继承混入类或直接在类对象上赋值实现，而非依赖字段注解。
attrs 以简洁、声明式的方式极大简化了 Python 数据类的定义，尤其擅长将类型注解自动转换为实例字段（instance fields）。但需注意：attrs 明确不支持将 typing.ClassVar 注解作为字段处理——它会直接跳过此类标注，既不生成实例属性，也不设置类属性。因此，如下写法无法达到预期效果：
from typing import ClassVar
from attrs import define
@define
class Person:
name: str
my_class_var: ClassVar[str] = "shared" # ❌ 不生效！该属性不会出现在实例或类上
p = Person("Alice")
# p.my_class_var # AttributeError!这是因为 attrs 的设计哲学是专注管理实例状态；类变量属于类本身的命名空间，应由 Python 原生机制管理。
✅ 正确实践：两种推荐方式
方式一：通过混入类（Mixin）继承类变量
定义一个仅含类变量的基类，让 @define 类继承它。attrs 不会干扰父类已存在的类属性：
from attrs import define, field
class SharedConfig:
version: str = "1.0.0"
default_timeout: int = 30
@define
class Person(SharedConfig):
name: str = field()
age: int = field()
p = Person("Bob", 28)
print(p.version) # → "1.0.0"（来自父类）
print(Person.version) # → "1.0.0"（类属性可直接访问）✅ 优势：结构清晰、支持多继承复用、IDE 可识别类型；适用于需跨多个
attrs类共享配置的场景。
方式二：类定义后动态赋值（推荐用于简单常量）
在 @define 装饰后，直接向类对象绑定属性：
from attrs import define, field
@define
class Person:
name: str = field()
age: int = field()
# 显式添加类变量
Person.API_BASE_URL = "https://api.example.com"
Person.MAX_AGE = 150
p = Person("Charlie", 35)
print(p.API_BASE_URL) # → "https://api.example.com"
print(Person.MAX_AGE) # → 150✅ 优势：简洁直观、无额外类开销；适合单点常量或运行时确定的类级配置。
⚠️ 注意事项与最佳实践
-
不要混淆
ClassVar与field(default=...)：后者创建的是所有实例共享的默认值（仍是实例属性），而非真正的类变量；修改它会影响单个实例，而非全局。 -
Final不等于ClassVar：Final[str]仅表示该实例字段不应被重新赋值，仍属于实例状态。 -
类型检查友好性：使用混入类时，建议为类变量添加类型提示（如
version: ClassVar[str]），虽attrs忽略它，但mypy等工具仍能校验访问合法性。 -
避免在
__init__中覆盖类变量：确保类变量名不与attrs字段名冲突，否则可能意外屏蔽类属性。
总之，attrs 的精妙在于“专注做好一件事”——管理实例字段。类变量应交还给 Python 的类机制处理。合理组合混入继承与类后赋值，即可在保持代码简洁的同时，获得类型安全、可维护且符合直觉的类设计。
