在 FastAPI 中自定义 Pydantic 的校验错误消息

最新推荐文章于 2025-09-12 00:34:42 发布

原创

最新推荐文章于 2025-09-12 00:34:42 发布 · 936 阅读

CC 4.0 BY-SA版权

文章标签：

FastAPI 是一个基于 Python 的高性能 Web 框架，专注于 API 开发，使用 Python 类型注解提供自动数据验证、序列化和高效的异步支持（基于 Starlette 和 Pydantic）。Pydantic 是一个数据验证和设置管理库，主要用于解析 JSON、校验数据类型。

Pydantic 添加校验条件是比较简单和自然的，然而如果要自定义错误消息则显得有些繁琐，下面来简单讨论一下。

在开始讨论之前，先提一下执行本文代码所依赖的包。为方便计，安装依赖包使用的是傻瓜式的安装方式。

安装命令如下：

pip install "fastapi[all]"

通过上面的安装命令，会安装许多和 fastapi 相关的依赖包，和本文中直接相关的两个包分别是 fastapi 和 pydantic。其中 fastapi 的版本是 fastapi==0.115.11, pydantic 的版本是 pydantic==2.10.6

本文使用的 Python 版本是 Python 3.9.6

Pydantic 为数据添加校验最简单的方式是使用 Field 给模型类的字段添加校验条件，如下所示：

from pydantic import BaseModel, Field  
  
class User(BaseModel):  
    username: str = Field(..., min_length=3)  
    age: int = Field(..., ge=0)

上面的代码看上去和许多库添加数据校验条件的方式差不多，不过这个 Field 有些迷惑性，它实际上是一个工厂函数，不像其他库那样是描述符。Field 工厂函数返回的是 FieldInfo 实例，FieldInfo 实现了类似描述符的功能，能对字段进行校验。

当提供的值通不过 FieldInfo 中定义的校验条件时，Pydantic 会抛出异常并给出错误消息。在上面的代码后面添加以下代码：

try:  
    user = User(username="ab", age=16)  
except ValidationError as e:  
    print(e.json())

运行上面的代码将输出：

[{
   
   "type":"string_too_short","loc":["username"],"msg":"String should have at least 3 characters","input"