7 使用 Pydantic 验证 FastAPI 的请求数据

news2025/2/11 8:48:57

FastAPI 是一个快速、现代的 Web 框架，它提供了自动生成 OpenAPI 文档的功能，支持 Pydantic 模型进行请求和响应数据的验证。Pydantic 提供了强大的数据验证功能，可以帮助你确保请求的有效性，自动进行数据转换，并生成详细的错误信息。

本文将介绍如何使用 Pydantic 验证 FastAPI 请求数据，包括如何处理请求体、查询参数、路径参数等。

1. 安装 FastAPI 和 Uvicorn

首先，如果还没有安装 FastAPI 和 Uvicorn，请运行以下命令进行安装：


pip install fastapi uvicorn

然后，你可以使用 Uvicorn 作为 ASGI 服务器来运行 FastAPI 应用：



uvicorn main:app --reload

2. 使用 Pydantic 验证请求体数据

FastAPI 允许你通过 Pydantic 模型来验证请求体中的数据。你只需要将 Pydantic 模型作为函数参数，FastAPI 会自动处理数据验证和转换。

2.1 定义 Pydantic 模型

首先，定义一个 Pydantic 模型来描述请求体的数据结构。例如，我们要创建一个用户注册接口，接收用户的姓名、年龄和邮箱地址。

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int
    email: str

在这个模型中：

name、age 和 email 是用户提交的数据字段。
str 和 int 是字段的数据类型，Pydantic 会自动验证和转换这些字段的数据。

2.2 定义 FastAPI 路由

然后，定义一个 FastAPI 路由来接收用户数据，并使用 Pydantic 模型进行验证。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str
    age: int
    email: str

@app.post("/users/")
async def create_user(user: User):
    return {"name": user.name, "age": user.age, "email": user.email}

在上面的代码中：

create_user 路由会接收一个 User 类型的请求体。
Pydantic 会自动验证请求体中的数据，如果数据无效（如类型错误或缺少必填字段），FastAPI 会返回 422 错误和详细的错误信息。

2.3 测试 API

现在，我们可以启动应用并通过 POST 请求来测试 API。例如，使用 curl 发送一个有效的请求：

curl -X 'POST' 'http://127.0.0.1:8000/users/' \
-H 'Content-Type: application/json' \
-d '{
    "name": "Alice",
    "age": 30,
    "email": "alice@example.com"
}'

响应将是：

{
  "name": "Alice",
  "age": 30,
  "email": "alice@example.com"
}

如果传入的数据无效（如 age 字段是字符串而不是整数），FastAPI 会返回 422 错误，响应如下：

{
  "detail": [
    {
      "loc": ["body", "age"],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ]
}

3. 验证查询参数和路径参数

除了请求体，FastAPI 还支持使用 Pydantic 验证查询参数和路径参数。

3.1 路径参数

FastAPI 允许你在路径中定义参数并进行验证。例如，我们可以定义一个路由来接收一个用户 ID，并返回该用户的基本信息：

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    return {"user_id": user_id}

在上面的代码中，user_id 是一个路径参数，FastAPI 会自动将其转换为整数，并验证其类型。如果传入的 user_id 无法转换为整数，FastAPI 会自动返回 422 错误。

3.2 查询参数

你还可以使用 Pydantic 验证查询参数。例如，我们可以让用户提供一个查询参数 q，来根据关键字查询用户：

from typing import Optional

@app.get("/users/")
async def search_users(q: Optional[str] = None):
    return {"query": q}

在这个例子中，q 是一个查询参数，它是可选的。如果没有传入查询参数，q 的默认值为 None。

你可以通过如下方式访问：

curl -X 'GET' 'http://127.0.0.1:8000/users/?q=Alice'

响应将是：

{
  "query": "Alice"
}

3.3 类型验证与转换

FastAPI 会自动验证查询参数的类型。如果你希望查询参数是整数类型，可以在参数声明中指定类型：

@app.get("/items/")
async def get_item(item_id: int):
    return {"item_id": item_id}

如果你访问 /items/?item_id=42，FastAPI 会自动将 item_id 转换为整数。如果传入无效类型（例如 item_id=abc），则 FastAPI 会返回 422 错误。

4. 自定义验证

如果你希望在 Pydantic 模型中进行更复杂的验证，可以使用 @validator 装饰器。假设你希望验证用户的 email 字段，确保它符合正确的格式：

from pydantic import validator, BaseModel

class User(BaseModel):
    name: str
    age: int
    email: str

    @validator('email')
    def email_format(cls, v):
        if '@' not in v:
            raise ValueError('Email must contain @ symbol')
        return v