pydantic 如何自定义 RootModel 处理整个 JSON 结构的校验

RootModel是Pydantic v2中用于校验无字段名的顶层jsON值（如纯列表、字典或原始值）的特殊模型，适用于输入本身就是单一层级数据的场景，而非替代BaseModel的通用容器。

RootModel 是什么，什么时候该用它

RootModel 是 Pydantic v2 引入的特殊模型，用于校验“没有字段名”的顶层 json 值，比如纯列表 [1, 2, "abc"]、纯字典 {"a": 1}，或任意单一层级的原始值。它不是用来替代 BaseModel 的通用容器，而是解决「整个输入就是一个值，而非键值对集合」的场景。

常见误用：想给 API 返回体加校验，却把 RootModel[list[Item]] 当成 “返回一个列表” 的万能包装——其实更推荐直接用 list[Item] 注解（Pydantic 自动推导），除非你明确需要复用校验逻辑或绑定方法。

怎么定义带自定义校验逻辑的 RootModel

不能像 BaseModel 那样在类体内写 @field_validator 或 @model_validator，因为 RootModel 没有字段名。校验必须作用于根值本身，方式是：

• 继承 RootModel 并指定泛型参数（如 RootModel[list[str]]）
• 重写 __init__ 或使用 @model_validator(mode="before") 处理传入的原始数据
• 注意：v2 中 @model_validator(mode="after") 对 RootModel 无效，它只在根值已转为 python 对象后运行，而此时类型已确定，无法拦截非法结构

示例：要求 JSON 必须是长度 ≥2 的非空字符串列表，并转为大写：

from pydantic import RootModel, model_validator 
class UppercaseStrList(RootModel[list[str]]): @model_validator(mode="before") def validate_and_transform(cls, v): if not isinstance(v, list): raise ValueError("root must be a list") if len(v) < 2: raise ValueError("list must contain at least 2 items") return [s.upper() if isinstance(s, str) else str(s).upper() for s in v]

RootModel 和 BaseModel 的嵌套使用陷阱

容易以为 RootModel[MyModel] 等价于 “一个 MyModel 实例”，但实际行为不同：

• RootModel[MyModel] 接收的是 raw input（如 dict），先按 MyModel 解析，再把结果赋给 .root 属性；它不提供 MyModel 的字段访问语法（如 .name），必须通过 .root.name
• 如果想保留字段访问能力，应该用普通 BaseModel + RootModel 作为类型注解（如函数返回 RootModel[MyModel]），而不是让它继承 RootModel
• JSON 序列化时：RootModel[MyModel](...).model_dump() 输出的是 MyModel 的字典，不是带 root 键的对象 —— 这点常被文档误导

为什么 .root 属性不可省略，以及如何安全暴露它

RootModel 的设计强制你通过 .root 访问内部值，这是为了语义清晰：它明确区分“模型实例”和“被包裹的值”。但这也带来两个现实问题：

• ide 不会自动补全 .root.xxx（因为 .root 类型是泛型，静态分析弱）
• 写 isinstance(obj.root, list) 比写 isinstance(obj, RootModel) 更啰嗦
• 解决方案：在子类中加属性代理，例如 @Property 转发常用操作，但注意别覆盖 .model_* 方法名

例如让 UppercaseStrList 支持直接调用 .append()：

class UppercaseStrList(RootModel[list[str]]):     # ... 上面的 validator 省略     @property     def root(self) -> list[str]:         return super().root 
def append(self, item: str) -> None:     self.root.append(item.upper())

不过要小心：这种代理只对明确写死的方法有效，无法泛化到所有列表方法，也不改变 RootModel 的核心约束 —— 它始终是单层封装，不是透明代理。