pydantic 的 `basemodel` 会将带类型注解的字段（如 `test_value: str = ""`）自动注册为模型字段，并在类定义阶段移除其作为类属性的存在，因此无法通过类名直接访问；它仅存在于实例中。
在 Pydantic 中，BaseModel 并非普通 Python 类——它通过自定义元类（ModelMetaclass）在类创建时对字段进行解析、验证和重构。当你声明：
from pydantic import BaseModel
class TestClass(BaseModel):
TEST_VALUE: str = ""Pydantic 会将 TEST_VALUE 视为一个模型字段（model field），而非传统意义上的类属性。这意味着：
- ✅ 它会被纳入模型的 __fields__、序列化/验证逻辑中；
- ❌ 它不会保留在类的 __dict__ 或 dir() 结果中；
- ✅ 实例化后，可通过 instance.TEST_VALUE 访问默认值或赋值后的值；
- ❌ 但 TestClass.TEST_VALUE 会触发 AttributeError（即使有默认值）。
验证行为（交互式示例）
>>> 'TEST_VALUE' in dir(TestClass) False >>> 'TEST_VALUE' in dir(TestClass()) True >>> TestClass().TEST_VALUE '' >>> TestClass.TEST_VALUE # AttributeError!
正确做法：区分「类属性」与「模型字段」
| 目标 | 推荐方式 | 说明 |
|---|---|---|
| 需要作为模型字段参与校验/序列化 | 保留字段定义（如 field_name: type = default）→ 仅实例可访问 | 这是 Pydantic 的设计初衷，适用于配置项、API 请求体等场景 |
| 需要真正的类属性（类级别共享、静态访问） | 使用 ClassVar 显式标注 | 告诉 Pydantic 忽略该属性，不将其视为模型字段 |
✅ 正确添加类属性的写法：
from pydantic import BaseModel
from typing import ClassVar
class TestClass(BaseModel):
# 模型字段（实例级）
name: str = "default"
# 类属性（类级别，可直接 TestClass.VERSION 访问）
VERSION: ClassVar[str] = "1.0.0"
MAX_RETRY: ClassVar[int] = 3
# ✅ 正常访问
print(TestClass.VERSION) # "1.0.0"
print(TestClass.MAX_RETRY) # 3
print(TestClass().name) # "default"
# print(TestClass().VERSION) # ❌ AttributeError（ClassVar 不挂载到实例）⚠️ 注意事项：
- ClassVar 是类型提示工具，必须配合 typing.ClassVar 使用，否则 Pydantic 仍可能误判；
- 不要混用 ClassVar 和默认值赋值来模拟“可选模型字段”——这会导致语义混乱；
- 若需环境变量加载 + 类级常量，建议将常量定义在模块顶层或独立配置类中，避免耦合。
总结：Pydantic 的字段机制优先服务于数据建模，而非通用类抽象。理解 BaseModel 的元类行为，合理使用 ClassVar，是避免此类 AttributeError 的关键。
