Python 数据校验逻辑如何集中管理

用 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)

校验逻辑一旦脱离模型定义，就等于把契约写在注释里——别人看不见，IDE 不提示，测试难覆盖，上线才爆。最麻烦的不是写 validator，是字段语义漂移时没人知道该改哪一行。