Pydantic v2 嵌套校验必须显式声明类型，dict/Any 不触发递归校验；需为每层定义 BaseModel 子类，否则字段缺失、类型错位等问题静默发生；RootModel 用于 list-of-dict 等非对象输入；慎用 validate_python(context=...) 影响性能；Self 支持递归但需 future 导入。
Pydantic v2 的 BaseModel 嵌套校验必须显式声明类型
Python 3.11 中 Pydantic v2 不再自动推断嵌套字典结构，dict 或 Any 类型字段不会触发递归校验。你得为每一层嵌套对象定义独立的 BaseModel 子类，否则缺失字段、类型错位、默认值不生效等问题会静默发生。
常见错误现象：ValidationError 提示 “field required” 却没报具体哪一层出错；或嵌套字典里传了字符串，校验却通过了。
- 嵌套字段必须用具体模型类名（如
UserProfile），不能用Dict[str, Any]替代 - 可选嵌套字段要配合
Optional[UserProfile]+= None，光写= None不够 - 若某层只是临时结构、不想建新类，可用
TypedDict配合model_config = {"extra": "forbid"}控制键名
用 RootModel 处理顶层非对象型嵌套输入（如列表套字典）
当你的入口数据是 [{"id": 1, "tags": ["a"]}] 这类 list-of-dict，直接传给普通 BaseModel 会报 Input should be a valid dictionary —— 因为默认只接受 dict 输入。
此时该用 RootModel[list[Item]]，它把整个输入当作根节点值来校验，而不是试图解析成某个字段。
立即学习“Python免费学习笔记（深入）”；
-
RootModel不支持model_dump()直接输出带字段名的 dict，它.root才是原始数据 - 如果还要加额外字段（比如分页元信息），就不能用
RootModel，得退回到包装一层ResponseData模型 - 注意
RootModel[list[Item]]中Item仍需是完整BaseModel，不能是dict
性能敏感场景下慎用 validate_python() 的 context 参数
在 Python 3.11 + Pydantic v2 中，validate_python() 比 model_validate() 快约 15–20%，尤其适合高频校验。但一旦启用 context=...（例如传入数据库 session 用于依赖检查），就会触发完整模型构建流程，失去速度优势。
容易踩的坑：为图方便在所有地方统一加 context={"user_id": ...}，结果发现 90% 的校验根本不用它，白白拖慢吞吐。
- 只在真正需要运行时上下文逻辑的地方传
context，比如自定义@field_validator(mode="before")中查库 - 校验纯结构数据（如 API 请求体）优先用
model_validate()或无context的validate_python() - 用
type_checking=True（默认开启）可跳过部分运行时类型检查，但仅限明确知道输入类型安全时才关
Python 3.11 的 Self 类型与嵌套循环引用处理
遇到树形结构（如评论回复链、组织架构）时，Pydantic v2 支持用 Self 声明递归字段，但 Python 3.11 要求必须配合 from __future__ import annotations，否则会报 NameError: name 'Self' is not defined。
典型写法：children: list[Self] | None = None，但得确保整个模块开头有未来导入，且不能和 from typing import Self 混用（后者在 3.11 是别名，行为不一致）。
- 循环引用模型之间不要互相 import 类，统一提到
if TYPE_CHECKING:块里做前向引用 -
Self只适用于单模型自引用；跨模型循环（A→B→A）仍得用字符串名称，如"BModel" - 校验深度超 100 层时会触发
RecursionError，可通过model_config = {"recursion_limit": 200}调整，但建议先检查数据是否异常
