本文介绍使用 Pydantic RootModel 构建递归嵌套字典模型（如多维计数表）的最佳实践，避免手动构造器，确保字段级类型校验、JSON 序列化/反序列化及 IDE 类型提示完整生效。
本文介绍使用 pydantic `rootmodel` 构建递归嵌套字典模型（如多维计数表）的最佳实践，避免手动构造器，确保字段级类型校验、json 序列化/反序列化及 ide 类型提示完整生效。
在 Pydantic v2 中，处理“任意深度嵌套、同构结构的字典”（例如表示笛卡尔积维度的计数表）时，最简洁且类型安全的方式是使用 RootModel —— 它专为直接建模根级数据结构（而非具名字段）而设计，天然支持递归类型注解与自动验证。
以下是一个完整、可运行的实现：
from pydantic import RootModel
from typing import Dict, Union, TYPE_CHECKING
if TYPE_CHECKING:
# 仅用于类型检查器推导，避免循环引用警告
NestedCounts = "NestedCounts"
class NestedCounts(RootModel):
root: Dict[str, Union["NestedCounts", int]]
✅ 关键优势说明：
-
原生类型检查生效：
model_validate()会严格校验每一层键是否为str、叶节点是否为int、中间节点是否为符合NestedCounts结构的字典——无需自定义@classmethod from_dict； -
IDE 友好：VS Code / PyCharm 能正确识别
nested_counts.root["x1"]["y2"]["z1"]的类型为int，支持跳转和补全； -
序列化开箱即用：
nested_counts.model_dump()返回原始嵌套字典，model_dump_json()输出标准 JSON； -
错误信息清晰：若输入中混入
float或None，Pydantic 将精准定位到出错路径（如root -> x1 -> y1 -> z1），远优于手动isinstance判断。
⚠️ 注意事项：
- 必须使用字符串字面量
"NestedCounts"进行前向引用（Python 3.7+ 支持），否则会导致NameError或类型解析失败； -
RootModel不提供.model_fields或命名字段访问，所有操作均通过.root属性进行； - 若需额外业务逻辑（如计算总和、扁平化），建议封装为实例方法或
@computed_field（需继承BaseModel并用model_config = {'extra': 'forbid'}+ 自定义__init__，但会牺牲纯RootModel的简洁性）。
? 进阶建议（可选）：
若后续需扩展为带元数据的结构（如添加 dimensions: List[str] 或 total: int 字段），可改用 BaseModel + Field(default_factory=dict) 配合 model_validator(mode='before') 实现混合模式，但对纯嵌套计数场景，RootModel 始终是最轻量、最符合 Pydantic 设计哲学的选择。
