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

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 BaseModelclass User(BaseModel):name: strage: intemail: str

在这个模型中：

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

2.2 定义 FastAPI 路由

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

from fastapi import FastAPI
from pydantic import BaseModelapp = FastAPI()class User(BaseModel):name: strage: intemail: [e-mail]("/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": "[e-mail]"
}'

响应将是：

{"name": "Alice","age": 30,"email": "[e-mail]"
}

如果传入的数据无效（如 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 [e-mail]("/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, BaseModelclass User(BaseModel):name: strage: intemail: str@validator('email')def email_format(cls, v):if '@' not in v:raise ValueError('Email must contain @ symbol')return v

如果提交的邮箱不包含 @ 符号，FastAPI 会抛出验证错误并返回相应的错误信息。

在 FastAPI 中，Pydantic 用于轻松地进行请求数据的验证和处理。通过定义 Pydantic 模型，你可以快速验证请求体、查询参数、路径参数等，并自动处理数据转换。FastAPI 会自动根据你的模型生成 API 文档，并且会在请求数据无效时提供详细的错误信息。

Pydantic 的强大验证能力和 FastAPI 的高效集成使得构建健壮的 API 变得更加简单。