通过继承 RootModel[str] 构建轻量验证模型，可使字段在序列化时直接展开为原始值（如 "xxx"），而非嵌套对象 { "bar": { "__root__": "xxx" } }，兼顾类型安全与 JSON 简洁性。
通过继承 `rootmodel[str]` 构建轻量验证模型，可使字段在序列化时直接展开为原始值（如 `"xxx"`），而非嵌套对象 `{ "bar": { "__root__": "xxx" } }`，兼顾类型安全与 json 简洁性。
在 Pydantic v2 中，若希望自定义类型（如 Foo）既保留数据校验能力，又在序列化时“透明”地展平为原始值（避免生成冗余嵌套结构），标准的 BaseModel 子类无法满足需求——因为 BaseModel 总会将其字段序列化为对象字典（例如 {"__root__": "xxx"} 或完整字段结构）。此时，RootModel 是专为此类场景设计的核心工具。
RootModel[T] 表示一个“根级模型”，其语义等价于一个被封装的单一值 T；序列化时默认输出该值本身，而非包装对象。例如：
from pydantic import RootModel, BaseModel
class Foo(RootModel[str]):
# 自动对字符串进行基础校验（如非 None、类型匹配）
# 可进一步添加 validator 或 field constraints
pass
class Bar(BaseModel):
bar: Foo
y = Bar(bar=Foo('xxx'))
print(y.model_dump_json()) # 输出: {"bar": "xxx"}✅ 关键优势：
-
Foo('xxx')仍执行完整验证（如传入None或123会抛出ValidationError）； -
Bar的bar字段类型清晰、IDE 友好、文档可生成； - 序列化结果完全扁平，符合 API 设计中对简洁 payload 的要求。
⚠️ 注意事项：
-
RootModel不支持Field(...)或额外字段——它仅封装一个根值；如需复杂校验（如正则、长度限制），应使用Annotated+AfterValidator组合，或在RootModel内定义model_validator； - 若仅需简单约束，推荐更轻量的
Annotated[str, AfterValidator(lambda s: s.strip())]方式，但RootModel在需复用、命名和类型别名场景下更具可维护性； -
model_dump_json()是推荐的序列化方法（替代已弃用的.json()），确保行为一致且支持现代选项（如exclude_none）。
总结：当需要「带校验的标量类型」且拒绝嵌套时，RootModel[T] 是 Pydantic v2 的标准解法。它让模型既是类型契约，又是序列化契约，真正实现验证与表现的解耦。
