用 pydantic basemodel 统一收口校验逻辑，将字段规则（必填、长度、正则、枚举）、自定义验证（@field_validator）、空格处理（before_validator）全部集中到模型定义中；fastapi 自动绑定校验并生成 openapi 文档；校验通过后用 model_dump 安全导出数据，避免直接传实例引发类型错误。
用 pydantic.BaseModel 统一收口校验逻辑
把校验逻辑散在函数里、if 判断里、甚至 SQL 查询前手动检查，后期改字段或加规则时根本没法维护。直接让 pydantic.BaseModel 承担输入/输出的契约职责，所有校验集中到模型定义里，调用方只管传字典或 JSON，失败就抛 ValidationError。
常见错误现象：手写 if not x or len(x) > 100 类校验，结果漏掉空格截断、大小写归一、None 和空字符串混判；或者多个接口对同一字段（如 email）写三套正则，一处改，四处崩。
- 必填字段用
Field(...)，非必填加默认值或Field(None) - 字符串长度、正则、枚举限制全写在
Field的min_length、pattern、in_参数里，别塞进方法里 - 自定义校验用
@field_validator装饰器，比如验证手机号是否带区号、密码是否含特殊字符——逻辑只写一次，所有用到该字段的模型自动继承 - 注意
BaseModel默认把str类型的输入转成str，但不会自动 strip 空格；需要的话显式加before_validator或在Field里用default_factory处理
API 层用 FastAPI 自动绑定模型校验
如果你用 FastAPI，根本不用手动调 .model_validate()。把 BaseModel 当参数类型注解，框架会在请求解析阶段自动校验并生成 OpenAPI 文档，422 错误会带具体字段和原因。
使用场景：HTTP POST 的 JSON body、Query 参数、Path 参数、Header 值——只要声明了类型是某个 BaseModel 子类，就生效。
立即学习“Python免费学习笔记（深入）”；
- Query 参数用
Query包一层再指定模型字段，比如q: MyQueryModel = Query(...) - Body 必须用
Body显式标记，否则 FastAPI 会当成路径参数处理；嵌套结构直接写body: MyNestedModel - 别在路由函数里再写
try...except ValidationError——FastAPI 已经帮你做了，重复捕获反而掩盖真实错误位置 - 性能影响几乎为零：校验发生在 ASGI middleware 阶段，不进业务函数；但模型定义太深（比如嵌套 10 层 + 每层都带 validator）会轻微拖慢解析
validate_python vs model_validate 怎么选
Pydantic v2 之后，model_validate 是实例方法，必须先有模型类；validate_python 是模块级函数，适合运行时动态校验原始数据，比如从缓存读出的 dict、第三方 SDK 返回的松散结构。
容易踩的坑：用 MyModel(**data) 替代校验——这跳过了所有 Field 规则和 validator，只做基本类型转换，等于裸奔。
- 已知结构且稳定 → 用
MyModel.model_validate(data)，语义清晰，IDE 可补全字段 - 数据来源不可控（如 Redis 里存的 dict，字段可能缺失或多出）→ 用
MyModel.model_validate(data, strict=False)，或更安全的validate_python(MyModel, data) - 想复用已有模型但只校验部分字段？别删字段重定义，用
model_copy(update={...})或临时构建type("Temp", (MyModel,), {})不推荐，优先考虑拆小模型 -
validate_python不走类的__init__，所以你在__init__里写的逻辑不会触发——校验和初始化要分清
校验后怎么安全地传给下游（DB / service）
校验通过的 BaseModel 实例不是“干净数据”，它带方法、配置、私有字段（如 _foo），直接传给 ORM 或 requests 库可能出错或泄露内部状态。
常见错误现象：把 user_model.dict() 传给 SQLAlchemy 的 **kwargs，结果 dict() 默认包含 Config 里设的 extra="ignore" 字段，或把 datetime 对象塞进 MySQL 的 execute()，报 TypeError: Object of type datetime is not JSON serializable。
- 传给 DB（如 SQLAlchemy）：用
model.model_dump(exclude_unset=True, exclude_none=True)，去掉未设置和 None 值，避免覆盖数据库默认值 - 传给 HTTP 请求体：用
model.model_dump(mode="json")，自动把datetime、UUID转成字符串，适配 JSON 序列化 - 别用
dict(model)——这是 v1 写法，v2 已废弃，行为不稳定 - 如果下游要求特定 key 名（比如 API 要
user_id，模型里是uid），在Field里用alias="user_id"，然后model_dump(by_alias=True)
