FastAPI教程：理解并使用Pydantic模型作为API请求体-Python教程-PHP中文网

FastAPI教程：理解并使用Pydantic模型作为API请求体

心靈之曲

发布： 2025-09-17 10:15:11

原创

724人浏览过

FastAPI教程：理解并使用Pydantic模型作为API请求体

本教程详细阐述了在FastAPI中如何高效地使用Pydantic模型作为API端点的请求体。FastAPI利用Pydantic的强大功能，自动进行请求数据的解析、验证和序列化。核心机制在于将传入JSON数据的键名与Pydantic模型中定义的字段名进行精确匹配。文章将通过具体的代码示例，演示Pydantic模型的定义、FastAPI端点的创建，以及如何构建符合预期的JSON请求体，确保数据传输的准确性和健壮性。

1. Pydantic模型在FastAPI中的作用

在fastapi中，pydantic模型扮演着至关重要的角色，它用于定义api请求体（request body）、响应体（response body）以及查询参数（query parameters）等的数据结构和验证规则。通过pydantic，fastapi能够自动完成以下任务：

数据验证： 确保接收到的数据符合预定义的类型和约束。
数据解析： 将传入的JSON或表单数据自动转换为Pydantic模型实例。
数据序列化： 将Pydantic模型实例转换为JSON格式以供响应。
自动文档生成： 根据Pydantic模型生成详细的OpenAPI（Swagger UI/ReDoc）文档，清晰展示API的输入输出结构。

2. 定义Pydantic模型

首先，我们需要定义Pydantic模型来描述我们期望的请求数据结构。以下是一个聊天消息相关的Pydantic模型示例：

from pydantic import BaseModel

# 基础聊天消息模型，定义了所有消息共有的字段
class ChatMessageBase(BaseModel):
    sender_id: int
    receiver_id: int
    message_content: str

# 用于创建聊天消息的模型，继承自ChatMessageBase
# 如果有额外的创建时特有字段，可以在这里添加
class ChatMessageCreate(ChatMessageBase):
    pass

# 用于表示已存储的聊天消息的模型，包含数据库生成的ID和时间戳
class ChatMessage(ChatMessageBase):
    message_id: int
    time_created: str # 实际应用中建议使用datetime类型

    class Config:
        # orm_mode = True 告诉Pydantic模型它可以从ORM对象中读取数据
        # 例如，当从数据库查询结果创建Pydantic实例时
        orm_mode = True

登录后复制

在这个示例中：

ChatMessageBase 定义了消息发送者ID、接收者ID和消息内容。
ChatMessageCreate 继承自 ChatMessageBase，表示在创建消息时需要提供这些字段。如果创建时有额外字段，可以添加到这个模型中。
ChatMessage 同样继承自 ChatMessageBase，并增加了 message_id 和 time_created 字段，这些通常是数据库在保存后生成的。Config.orm_mode = True 对于与ORM（如SQLAlchemy）集成非常有用。

3. 定义FastAPI端点

接下来，我们将定义一个FastAPI端点，它将接收一个Pydantic模型作为请求体。

from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session # 假设使用SQLAlchemy

# 导入上面定义的Pydantic模型
import schema # 假设Pydantic模型定义在schema.py文件中
import crud # 假设crud.py包含数据库操作逻辑

app = FastAPI()

# 模拟数据库会话依赖项
def get_db():
    db = Session() # 实际应用中应配置数据库连接
    try:
        yield db
    finally:
        db.close()

# 定义一个POST请求端点，接收ChatMessageCreate模型作为请求体
@app.post("/assistant_chat/")
def create_chat_message(chat_message: schema.ChatMessageCreate, db: Session = Depends(get_db)):
    """
    创建一个新的聊天消息。
    接收一个Pydantic ChatMessageCreate模型作为请求体。
    """
    # crud.create_chat_message 负责将数据保存到数据库
    # 它将接收一个Pydantic模型实例
    return crud.create_chat_message(db=db, chat_message=chat_message)

登录后复制

在 @app.post("/assistant_chat/") 装饰器下，create_chat_message 函数的参数 chat_message: schema.ChatMessageCreate 是关键。FastAPI会根据这个类型提示自动识别：

这是一个请求体参数。
期望的请求体数据结构应符合 schema.ChatMessageCreate Pydantic模型。
FastAPI将尝试把传入的JSON请求体解析并验证为 schema.ChatMessageCreate 的实例。

4. 构建并发送请求体

当FastAPI端点期望一个Pydantic模型作为请求体时，客户端需要发送一个JSON对象，其键名（keys）必须与Pydantic模型中定义的字段名（field names）精确匹配。FastAPI会根据这些匹配关系将JSON值映射到Pydantic模型实例的相应属性上。

对于上述 ChatMessageCreate 模型，它继承自 ChatMessageBase，因此需要 sender_id, receiver_id, message_content 这三个字段。

文心大模型

百度飞桨-文心大模型 ERNIE 3.0 文本理解与创作

查看详情

正确的JSON请求体示例：

{
    "sender_id": 101,
    "receiver_id": 202,
    "message_content": "你好，FastAPI！"
}

登录后复制

使用Python requests 库发送请求：

import requests
import json

# FastAPI应用的URL
BASE_URL = "http://127.0.0.1:8000" # 假设FastAPI运行在8000端口

# 准备请求体数据，作为Python字典
payload = {
    "sender_id": 101,
    "receiver_id": 202,
    "message_content": "这是一条测试消息。"
}

# 发送POST请求
try:
    response = requests.post(f"{BASE_URL}/assistant_chat/", json=payload)

    # 检查响应状态码
    if response.status_code == 200:
        print("消息发送成功！")
        print("响应数据:", response.json())
    else:
        print(f"请求失败，状态码: {response.status_code}")
        print("错误信息:", response.json())

except requests.exceptions.ConnectionError as e:
    print(f"无法连接到FastAPI服务，请确保服务正在运行: {e}")

登录后复制

在 requests.post() 方法中，使用 json=payload 参数非常重要。requests 库会自动将Python字典 payload 序列化为JSON格式，并设置正确的 Content-Type: application/json 请求头。

5. FastAPI的自动映射机制

FastAPI的强大之处在于其与Pydantic的深度集成。当接收到 Content-Type: application/json 的请求时，FastAPI会执行以下步骤：

解析JSON： 将请求体中的JSON字符串解析为Python字典。
类型匹配： 查找端点函数参数中带有Pydantic模型类型提示的参数（例如 chat_message: schema.ChatMessageCreate）。
字段映射： 将解析后的Python字典的键与Pydantic模型中定义的字段名进行匹配。如果键名一致，则将对应的值赋给Pydantic模型实例的属性。
数据验证： Pydantic会根据模型中定义的类型（如 int, str）和任何其他验证规则（如 min_length, max_value）对数据进行验证。
实例创建： 如果所有数据都通过验证，FastAPI会创建一个Pydantic模型实例，并将其作为参数传递给端点函数。
错误处理： 如果数据验证失败（例如，sender_id 应该为 int 但接收到了 string，或者缺少了必需的字段），FastAPI会自动返回一个 422 Unprocessable Entity 错误，并附带详细的错误信息，说明哪些字段不符合要求。

6. 注意事项与最佳实践

键名匹配： JSON请求体中的键名必须与Pydantic模型中的字段名完全一致（区分大小写）。
类型提示： 始终为Pydantic模型字段使用准确的类型提示，FastAPI和Pydantic会利用这些信息进行验证。
必需字段： 默认情况下，Pydantic模型中定义的字段都是必需的。如果字段是可选的，应使用 Optional 或设置默认值。
自动文档： 充分利用FastAPI自动生成的Swagger UI (/docs) 和 ReDoc (/redoc) 文档。它们会清晰地展示每个端点期望的请求体结构，这对于调试和API消费者非常有帮助。
错误处理： 熟悉FastAPI的 422 Unprocessable Entity 错误响应结构，它会提供详细的验证失败信息，帮助客户端快速定位问题。

总结

通过Pydantic模型，FastAPI提供了一种声明式且高效的方式来处理API的请求体。开发者只需定义清晰的数据模型，FastAPI便能自动处理繁琐的数据解析、验证和序列化工作。理解JSON键与Pydantic模型字段的匹配机制是成功构建和使用FastAPI请求体的关键。这种集成不仅简化了后端开发，也提升了API的健壮性和可维护性。

以上就是FastAPI教程：理解并使用Pydantic模型作为API请求体的详细内容，更多请关注php中文网其它相关文章！