Python如何编写健壮的API接口_使用pydantic进行输入Schema异常校验-Python教程-PHP中文网

pydantic v2 中 basemodel 必须用 model_validate 替代 parse_obj，且 fastapi 中需用 body(embed=true) 处理嵌套 json；field(default_factory=...) 可区分“未提供”与“传 null”；validationerror.errors() 提供结构化错误信息。

python如何编写健壮的api接口_使用pydantic进行输入schema异常校验

Pydantic v2 的 `BaseModel` 必须用 `model_validate` 替代 `parse_obj`

很多老项目迁移到 Pydantic v2 后，接口校验突然抛出 AttributeError: type object 'MyModel' has no attribute 'parse_obj'。这是因为 v2 彻底移除了 parse_obj、parse_raw 等旧方法，统一用 model_validate（校验 Python 字典）和 model_validate_json（校验 JSON 字符串）。

实际写 FastAPI 接口时，你通常不需要手动调用这些——FastAPI 内部已自动使用 model_validate 处理请求体。但如果你在中间件、工具函数或单元测试中手动实例化模型，就得立刻改掉：

from pydantic import BaseModel
<p>class UserCreate(BaseModel):
name: str
age: int</p><h1>✅ 正确（v2）</h1><p>user = UserCreate.model_validate({"name": "Alice", "age": 30})</p><h1>❌ 错误（v1 风格，v2 报错）</h1><h1>user = UserCreate.parse_obj({"name": "Alice", "age": 30})</h1>

别依赖 IDE 自动补全的旧方法名，查官方文档确认当前版本 API
model_validate 默认 strict=False，允许类型强制转换（如把字符串 "25" 转成 int），如需严格模式，加参数 strict=True
若输入是 bytes 或 str 格式的 JSON，必须用 model_validate_json，否则会误把 JSON 字符串当普通字段值处理

FastAPI 中 `Body` 参数未设 `embed=True` 导致 422 错误却不报具体字段

当你定义一个嵌套 Body 模型，比如 POST /users 接收 {"user": {"name": "Bob", "age": 28}}，但 Pydantic 模型直接写成 UserCreate，FastAPI 默认会期望顶层 JSON 就是模型字段——即 {"name": "Bob", "age": 28}。如果实际传了带外层 key 的结构，就会返回模糊的 422，且错误信息里只显示 value_error.missing，不提是哪个字段缺失。

根本原因是 FastAPI 没把外层 user 当作“包装键”，而是当成多余字段忽略，导致内层字段全丢失。

解决方法：显式用 Body(embed=True) 告诉 FastAPI 把整个 body 包进一个 key 里校验

示例：

from fastapi import Body
from pydantic import BaseModel
<p>class UserCreate(BaseModel):
name: str
age: int</p><p>@app.post("/users")
def create_user(user: UserCreate = Body(..., embed=True)):
return user</p>

此时客户端必须传 {"user": {"name": "Bob", "age": 28}}；若想兼容两种格式，得用两个不同 endpoint 或自定义依赖项

用 `Field(default=...)` 和 `Field(default_factory=...)` 区分“空值”与“未提供”

API 常见需求：某些字段可选，但需要知道用户是“没传这个字段”，还是“传了 null/empty 字符串”。比如更新接口中，PUT /users/123 只改名字，不希望年龄被意外清零。

Claw Code Suite (Python-Only Edition)

仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...

下载

Pydantic 的 Field(default=None) 无法区分“用户传了 "age": null” 和 “压根没传 age 字段”。真正可控的方式是用 default_factory + 自定义标记对象：

from pydantic import BaseModel, Field
from typing import Any
<p>_unset = object()  # 唯一哨兵值</p><p>class UserUpdate(BaseModel):
name: str | None = None
age: int | None = Field(default_factory=lambda: _unset)</p><pre class="brush:python;toolbar:false;">def get_updated_fields(self) -> dict[str, Any]:
    return {k: v for k, v in self.__dict__.items() if v is not _unset}

default_factory 在每次实例化时调用，确保每次都是新哨兵，避免可变默认值陷阱
Field(default=None) 表示“允许为 None”，但不会帮你判断是否用户主动提交了 None
若用 Optional[int] + Field(default=None)，用户传 {"age": null} 和不传 age 都会导致 age == None，无法区分

自定义错误信息要用 `ValidationError` 的 `errors()` 而非 `str(e)`

很多人在异常处理器里直接 str(e) 返回给前端，结果得到一长串带文件路径、行号、内部类名的 traceback 式文本，既难读又暴露服务细节。Pydantic 的 ValidationError 提供了结构化的 errors() 方法，返回标准字典列表。

FastAPI 默认已做了这层封装，但如果你在非 FastAPI 场景（如 CLI 工具、后台任务）手动校验，就得自己处理：

try:
    user = UserCreate.model_validate(data)
except ValidationError as e:
    # ✅ 结构化输出，前端可直接解析
    errors = [
        {"field": ".".join(err["loc"]), "msg": err["msg"], "type": err["type"]}
        for err in e.errors()
    ]
    raise HTTPException(422, detail=errors)

e.errors() 每个元素含 loc（字段路径，如 ["age"] 或 ["items", 0, "price"]）、msg、type
不要用 json.loads(str(e)) 或正则提取——str(e) 格式不稳定，v2 之后还可能变化
若需国际化错误文案，应在 Field(..., description="年龄必须大于 0") 之外，用自定义 validator + raise ValueError("年龄不能为负")，再统一捕获转译

最易被忽略的一点：Pydantic 的字段校验发生在模型实例化**之前**，所以即使你写了 @field_validator("age")，只要输入连基本类型都过不了关（比如传字符串 "abc" 给 int 字段），自定义 validator 根本不会执行——错误直接卡在类型转换阶段。要覆盖这类底层转换逻辑，得用 @field_serializer 或自定义 __pydantic_core_schema__，代价很高，通常应优先约束前端传参规范。