登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  文章 >  python教程

Pydantic model_validate_json 怎样在严格模式下解析请求体

来源:17golang原创

时间:2026-11-16 22:35:52 417浏览 收藏

如果请求体本来就是 JSON 文本,推荐直接调用 model_validate_json(),不要为了“严格校验”先无条件执行 json.loads()。这样 Pydantic 能同时看到 JSON 的原始表示和模型的严格配置:日期字符串可以按 JSON 规则转成日期,数组也可以按 JSON 规则进入元组;而已经变成 Python 字典的数据,则应使用 model_validate(),它遵循 Python 对象的严格类型边界。

官方资料:https://pydantic.dev/docs/validation/latest/concepts/json/

这篇文章只解决一个容易混淆的问题:同一个数据,为什么交给 model_validate_json() 和 model_validate() 后,在 strict=True 下可能得到不同结果。

原始 JSON 请求体经过 model_validate_json 进入严格 Pydantic 模型的结构示意图
图1:原始 JSON 到严格模型的输入关系说明图,不是运行截图。

一、先记住结论:按输入形态选择入口

可以把校验入口简单分成两类:

手里的数据推荐入口校验时关注什么
HTTP 请求体中的 JSON 字符串、字节或字节数组model_validate_json()JSON 语法、JSON 表达和模型字段
已经由代码组装好的 Python 字典或对象model_validate()Python 对象的实际类型
只想解析任意 JSON 结构pydantic_core.from_json() 或普通 JSON 解析器是否需要后续模型校验

这里的“严格”不是拒绝一切表示层转换,而是拒绝不符合 Python 类型契约的对象。JSON 没有原生的日期和元组,Pydantic 必须允许一些有边界的 JSON 到目标类型转换,否则严格模型无法表达常见请求体。

二、用一个严格模型接收 JSON 请求体

下面的模型刻意放入日期和元组两个字段:它们在 JSON 中分别表现为字符串和数组,正好能观察 JSON 输入的语义。

from datetime import date

from pydantic import BaseModel, ConfigDict


class Event(BaseModel):
    # 严格模式约束 Python 对象,但不会抹掉 JSON 表示层的必要转换
    model_config = ConfigDict(strict=True)

    when: date
    where: tuple[int, int]


payload = '{"when": "2026-11-16", "where": [120, 30]}'

# 请求体仍是 JSON 文本,交给 JSON 专用入口
event = Event.model_validate_json(payload)
print(event.when, event.where)
# 结果示意:2026-11-16 (120, 30)

关键点是 payload 仍然是 JSON 字符串。Pydantic 先解析 JSON,再根据 JSON 中允许的表示把日期字符串和数组映射到模型字段。这个行为并不等于对所有 Python 值都放宽类型。

三、strict=True 为什么仍能处理日期和数组

严格模式最容易被误读成“任何字符串都不能进入日期字段、任何列表都不能进入元组字段”。实际上,输入来源会影响判断:

  • 对 JSON 输入,日期没有 JSON 原生类型,所以日期字符串是日期的正常 JSON 表示。
  • 对 JSON 输入,元组没有 JSON 原生类型,所以数组可以作为元组的序列化表示。
  • 对已经存在的 Python 对象,字符串就是字符串,列表就是列表,不会因为它们“看起来像”目标值就自动变成日期或元组。

因此,严格模式是在两个层面共同工作:它保留 Python 类型契约,同时允许 JSON 表示层完成必要的、可解释的转换。不要只看字段类型,还要先确认数据有没有经过 JSON 边界。

四、model_validate_json 与 model_validate 的差别

把同样的逻辑改成 Python 字典后,结果会变得更严格:

from pydantic import ValidationError

python_object = {
    # 这里已经是 Python 字符串,不再是 JSON 表示层
    "when": "2026-11-16",
    # 这里已经是 Python list,不是 JSON 数组的原始文本
    "where": [120, 30],
}

try:
    # 严格模型会按 Python 对象的真实类型检查
    Event.model_validate(python_object)
except ValidationError as exc:
    # 只打印结构化错误,便于接口层记录字段位置和错误类型
    for error in exc.errors():
        print(error["loc"], error["type"])
# 结果示意:when/date_type;where/tuple_type

这就是“先 json.loads() 再 model_validate()”可能带来的差异。对于普通宽松模型,两种写法可能都能通过;但一旦打开严格模式,数据边界已经改变,校验器看到的就不再是原始 JSON。

model_validate_json 与 model_validate 在严格模式下处理 JSON 表示和 Python 对象的对照结构图
图2:两个校验入口的类型转换边界对照图,不是运行截图。

五、错误处理:不要把 JSON 错误和字段错误混成一类

model_validate_json() 的输入可能在两个位置失败:第一层是 JSON 文本本身无法解析,第二层是 JSON 能解析但字段不符合模型。对外返回时可以统一为“请求体无效”,对日志和监控则应保留结构化错误。

from pydantic import ValidationError


def parse_event(raw_body: str) -> Event:
    # 统一从原始请求体进入,避免无意中改变 JSON 语义
    try:
        return Event.model_validate_json(raw_body)
    except ValidationError as exc:
        # errors() 给出 loc、type、msg 和 input,适合记录诊断信息
        details = [
            {"loc": list(item["loc"]), "type": item["type"], "msg": item["msg"]}
            for item in exc.errors()
        ]
        # 生产代码可将 details 映射成统一的 400 响应
        raise ValueError({"request_body_invalid": details}) from exc

不要把 ValidationError 的消息直接拼成 HTML 返回给用户,也不要把完整的请求体写进日志。字段位置和错误类型通常已经足够定位问题;如果输入包含敏感信息,日志还应继续做脱敏。

六、实际项目中怎样选才不绕

可以采用一条很简单的边界规则:数据刚跨过 JSON 边界时用 model_validate_json(),数据已经被业务代码组装成 Python 对象时用 model_validate()。不要为了让两个入口“表现一致”而盲目关闭严格模式。

  1. 接口接收层保留原始 JSON 文本或字节,直接交给 model_validate_json()。
  2. 内部服务调用如果传递的是 Python 字典,使用 model_validate(),并让调用方提供正确的 Python 类型。
  3. 如果测试要模拟真实 HTTP 请求,测试数据应保留 JSON 字符串;如果测试的是内部函数,使用已经构造好的 Python 对象更直接。
  4. 当某个字段确实允许多种 Python 表达时,优先在字段类型或转换层明确写出规则,不要依赖入口差异“碰巧通过”。

总结

model_validate_json() 不是 model_validate() 的字符串别名。前者知道输入来自 JSON,因此在 strict=True 下仍能处理日期字符串、数组等 JSON 表示;后者面对的是已经存在的 Python 对象,会严格检查它们的真实类型。

记住三句话即可:原始请求体直接用 model_validate_json();Python 字典使用 model_validate();错误处理保留 ValidationError.errors() 的结构化信息。

常见问题

已经 json.loads() 了,还能继续使用严格模型吗?

可以,但此时应把它当作 Python 对象使用 model_validate(),不能再期待 JSON 表示层的日期和元组转换。若希望保留这部分语义,应直接把原始 JSON 交给 model_validate_json()。

model_validate_json 只接受字符串吗?

不只接受字符串,也可以接收字节或字节数组。实际项目应以框架交给你的请求体类型为准,不必为了调用它先做一次无意义的编码转换。

为什么 strict=True 不是“零转换”?

因为 JSON 本身没有日期、元组等原生类型。严格校验仍要理解这些类型的 JSON 表示,否则模型无法接收正常的接口数据。真正被收紧的是 Python 对象层的类型边界。

接口层要不要把所有 ValidationError 细节返回给客户端?

不建议。客户端可以得到字段位置和简短提示,内部日志保留错误类型;原始输入、密钥、令牌和完整请求体不要直接写入日志或错误响应。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>