Python接口参数校验设计_避免脏数据进入系统【技巧】

Pydantic BaseModel 提供自动类型转换、多级校验与错误聚合：str 用 min_length=1 拦截空白符，int 自动转类型并报错，嵌套结构逐层校验；Query/Path/Body 需分入口校验；业务规则用 @field_validator 或 @model_validator 统一处理，避免路由中手动 try/except。

用 pydantic 定义请求模型，而不是手写 if/else

直接在 FastAPI 或 Flask 中用 if 判断字段类型、长度、是否为空，短期快，长期难维护，且容易漏掉边界情况（比如空字符串当 None、数字字符串没转类型）。pydantic 的 BaseModel 能自动完成类型转换 + 校验 + 错误聚合。

• str 字段加 min_length=1 比 if not value: 更准——它能拦住空白符（"\t\n "）
• int 字段声明后，传入 "123" 会自动转成 123；传入 "abc" 直接报 value_error，不进业务逻辑
• 嵌套结构（如地址对象）也能一层层校验，不用手动 dict.get("addr", {}).get("city")

from pydantic import BaseModel, Field

class CreateUserRequest(BaseModel):
    name: str = Field(..., min_length=2, max_length=20)
    age: int = Field(..., ge=0, le=150)
    email: str = Field(..., regex=r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$")

区分 Query、Path、Body 的校验入口点

不是所有参数都该塞进同一个 BaseModel。FastAPI 会根据参数来源自动调用不同校验逻辑，混用会导致默认值失效或错误提示不清晰。

• Query 参数（URL ?key=value）适合用 Query(default=None, min_length=1) 单独约束，避免把可选查询条件硬塞进请求体模型
• Path 参数（如 /users/{uid}）必须用 Path(..., ge=1) 显式声明校验，否则 uid=0 或负数可能绕过检查
• Body（JSON 请求体）才用 BaseModel 类；若同时有 body + query，FastAPI 会合并报错信息，但各字段的校验上下文要分开写

自定义校验用 @field_validator，别在路由函数里 try/except

业务规则（比如“密码不能和用户名相同”“结束时间不能早于开始时间”）不适合塞进字段级约束，硬写会破坏模型复用性。用 @field_validator 在模型层面统一拦截，错误仍归到对应字段，前端能精准提示。

• 多个字段交叉校验时，用 @model_validator(mode="after")，取 self.field1 和 self.field2 对比
• 避免在路由函数里捕获 ValidationError 再包装返回——FastAPI 默认已处理，重复 catch 会让堆栈变深、错误位置偏移
• 自定义错误消息用 raise ValueError("起止时间顺序错误")，pydantic 会自动转成标准 JSON 错误格式

from pydantic import field_validator

class TimeRangeRequest(BaseModel):
    start: datetime
    end: datetime

    @field_validator("end")
    def end_after_start(cls, v, info):
        start = info.data.get("start")
        if start and v <= start:
            raise ValueError("end must be after start")
        return v

生产环境关掉 extra="forbid" 以外的宽松模式

开发时开 extra="ignore" 看似方便，但会让前端多传字段（比如调试加的 _debug=1）静默丢弃，后期排查问题时找不到数据去向。更危险的是 extra="allow" —— 任意字段都能进模型，等于放弃字段白名单控制。

• 始终设 model_config = ConfigDict(extra="forbid")，多传字段直接报 extra_forbidden
• 若需兼容旧字段，用 Field(default=None, exclude=True) 显式声明并忽略，而不是靠 ignore 模糊处理
• Swagger UI 中看到的请求示例，会严格按模型字段生成，避免误导前端传参

最常被忽略的是：校验不是越严越好，而是要让错误发生在**离用户最近的地方**——URL 解析失败、JSON 解析失败、字段校验失败，这三个层级的错误信息必须互不干扰，且能准确定位到具体字段名和原因。否则一个 422 Unprocessable Entity 返回几十行嵌套错误，前端根本没法映射到表单控件。