通过继承 RootModel[str] 构建自定义类型，可在保留完整字段验证能力的同时，使模型序列化输出扁平化（如 {"bar": "xxx"}），避免多余嵌套层级。
通过继承 `rootmodel[str]` 构建自定义类型，可在保留完整字段验证能力的同时，使模型序列化输出扁平化（如 {"bar": "xxx"}），避免多余嵌套层级。
在 Pydantic v2 中，若希望某个字段（如 bar）既接受定制化验证逻辑（例如非空字符串、长度限制、正则匹配等），又在序列化时不包装为对象（即不输出 {"bar": {"root": "xxx"}}），标准的 BaseModel 子类无法满足需求——因为它默认将整个模型序列化为一个 JSON 对象。
此时，RootModel 是专为此类场景设计的核心工具。它表示“根级值模型”，其本质是将一个单一值（如 str、int、list 等）作为模型的“根”，而非字段容器。当 Foo 继承 RootModel[str] 时：
- 实例化
Foo('xxx')等价于持有并验证该字符串； - 序列化时（如
.model_dump()或.model_dump_json()）直接输出"xxx"，而非{"root": "xxx"}； - 在组合模型（如
Bar）中作为字段类型使用时，自动融入父级 JSON 结构，实现扁平化输出。
✅ 正确实现示例：
from pydantic import RootModel, BaseModel
class Foo(RootModel[str]):
# 可添加验证逻辑，例如：
def __init__(self, value: str):
if not isinstance(value, str) or not value.strip():
raise ValueError("Foo must be a non-empty string")
super().__init__(value.strip())
class Bar(BaseModel):
bar: Foo
y = Bar(bar=Foo('xxx'))
print(y.model_dump_json()) # 输出：{"bar": "xxx"}⚠️ 注意事项：
RootModel不支持.model_fields或传统字段声明（如field(default=...)），所有逻辑需通过__init__、@field_validator（作用于root字段）或@model_validator实现；-
若仅需轻量验证（如非空、正则），更推荐使用
Annotated+AfterValidator（语义更清晰、无运行时开销）：from pydantic import AfterValidator, BaseModel, Field from typing import Annotated def non_empty_str(v: str) -> str: if not v.strip(): raise ValueError("must be non-empty") return v.strip() class Bar(BaseModel): bar: Annotated[str, AfterValidator(non_empty_str)] RootModel适用于需复用验证逻辑 + 类型别名的场景；而Annotated更适合一次性、轻量约束。
总之，RootModel[str] 是实现「验证存在、序列化隐形」的关键机制，合理选用可显著提升 API 响应结构的简洁性与兼容性。
