最省力的方式是用 Pydantic v2+ 定义 BaseModel 子类，明确字段类型与嵌套子模型，再调用 model_validate 递归校验；它自动检查类型、缺失/多余字段、越界等，避免手写多层 if 判断的漏检问题。
用 pydantic 定义模型后直接调用 model_validate
嵌套字典或 JSON 数据合法性校验最省力的方式，是提前声明结构约束，让校验逻辑下沉到类型定义里。用 pydantic（v2+）定义一个 BaseModel 子类，字段类型写清楚，嵌套结构用子模型表示，然后对原始数据调用 model_validate 即可——它会递归检查每一层，类型不符、字段缺失、多余字段、数值越界等都会抛出 ValidationError。
常见错误现象：手写多层 if isinstance(..., dict) + get() 判断，漏掉某一层的 None 检查，或没处理空列表/空字符串边界情况，结果运行时才崩。
-
model_validate默认严格校验，不接受多余字段（除非显式设model_config = ConfigDict(extra="ignore")） - 嵌套列表需用
List[SubModel]或list[SubModel]（Python 3.9+），不能只写list - 如果输入是 JSON 字符串，先用
json.loads()解析成 Python 对象再传入，别直接传字符串给model_validate
遇到动态键名（如用户 ID 作 key）怎么办？
当嵌套结构里某一层是字典，但 key 不固定（比如 {"u1001": {...}, "u1002": {...}}），pydantic 的 Dict[str, SubModel] 能覆盖，但要注意：key 类型必须明确（通常是 str），value 类型必须是可校验对象（不能是 dict 或 Any）。
使用场景：配置中心下发的用户维度策略、API 返回的按 ID 索引的资源集合。
立即学习“Python免费学习笔记（深入）”；
- 不要用
Dict[str, dict]—— 这会跳过 value 的结构校验 - 若 key 是数字字符串但需转为 int 做后续处理，可在子模型中用
Field(..., alias="u1001")配合model_validator提前转换，或在校验后统一映射 - 若 key 格式不规则（含特殊字符），考虑改用列表 +
id字段，更利于校验和序列化
typeguard 适合已有类型注解但不想改模型定义的场景
如果你的函数参数已有完整的类型提示（比如 def handle(data: dict[str, list[User]])），又不想引入 pydantic 模型类，typeguard 的 check_type 可直接校验运行时值是否匹配注解，包括嵌套结构。
性能影响：比 pydantic 模型验证慢约 3–5 倍（因无编译缓存），但胜在零侵入——不改函数签名，不加装饰器也能手动调用。
- 对
Union和Optional支持良好，但复杂泛型如TypedDict嵌套需额外注册 - 错误信息不如
pydantic清晰（比如只报 “expected list, got str”，不指出在第几层”） - 不校验字段语义（如邮箱格式、URL 是否有效），仅做类型层面匹配
别忽略 ValidationError 的细节提取
校验失败时，pydantic 抛出的 ValidationError 对象自带 errors() 方法，返回结构化错误列表，每个元素含 loc（定位路径）、msg（提示）、type（错误类型）。这比捕获异常后 print 一长串强得多。
容易踩的坑：直接 str(e) 打日志，丢失层级信息；或只检查 e.errors()[0]，忽略多个并发错误。
-
loc是 tuple，例如("users", 0, "email")表示 users 列表第 0 项的 email 字段 - 用
json.dumps(e.errors(), indent=2)输出调试，比默认字符串更易读 - 生产环境建议提取
loc和msg组装成业务友好的提示，而不是暴露原始错误类型
