FastAPI 请求体解析：基础概念与综合应用

本文深入探讨了 FastAPI 中的请求体概念，强调使用 Pydantic 模型来声明请求体数据结构。通过具体示例，展示了如何定义请求体、可选参数及默认值，提升数据验证和类型提示的便利性。文章还说明了如何在路径操作函数中结合使用请求体、路径参数和查询参数，使得 API 设计更为灵活。提供了多个示例代码，帮助开发者理解和实现这些特性，从而构建健壮的 API 接口。

示例使用 Python 版本为 Python 3.10.15 。

一 基础概念

请求体是客户端发送给 API 的数据。响应体是 API 发送给客户端的数据。在FastAPI中建议使用 Pydantic 模型声明请求体。示例如下：

from fastapi import FastAPI
from pydantic import BaseModelclass Item(BaseModel):name: strdescription: str | None = Noneprice: floattax: float | None = Noneapp = FastAPI()@app.post("/items/")
# 请求体参数的类型为 Item 模型
async def create_item(item: Item):return item

在这个例子中，数据模型 Item 声明为继承 Pydantic 的 BaseModel 类，Item 中的所有属性和声明查询参数一样，包含默认值的模型属性是可选的，否则就是必选的（默认值为 None 的模型属性也是可选的）。示例可以运行代码文件 chapter04.py 来启动应用：

$ uvicorn chapter04:app --reload

在线 SwaggerUI 文档，访问以下 URL ：

http://127.0.0.1:8000/items/

HTTP 方法为 POST，请求体为：

{"name": "测试","description": "测试描述","price": 0,"tax": 0
}

由于 description 和 tax 是可选的（默认值为 None），请求体的 JSON 对象也可以是这样：

{"name": "测试","price": 0
}

二 编辑器支持

Pydantic 模型在编辑器中，函数内部均可使用类型提示、代码补全。如果使用 字典，就没有这样的支持。如图所示:

这是 PyCharm 的截图，使用 PyCharm ，建议安装 Pydantic PyCharm 插件 ，该插件用于完善 PyCharm 对 Pydantic 模型的支持。

三 使用模型

@app.post("/items02/")
async def create_item02(item: Item):item_dict = item.dict()if item.tax:price_with_tax = item.price + item.taxitem_dict.update({"price_with_tax": price_with_tax})return item_dict

在 路径操作函数 内部直接访问模型对象的属性 price_with_tax = item.price + item.tax 。

四 请求体 + 路径参数

FastAPI 支持同时声明路径参数和请求体。FastAPI 能识别与路径参数匹配的函数参数，还能识别从请求体中获取的类型为 Pydantic 模型的函数参数。

@app.put("/items03/{item_id}")
async def update_item03(item_id: int, item: Item):return {"item_id": item_id, **item.dict()}

五 请求体 + 路径参数 + 查询参数

FastAPI 支持同时声明请求体、路径参数和查询参数。FastAPI 能够正确识别这三种参数，并从正确的位置获取数据。

@app.put("/items04/{item_id}")
async def update_item04(item_id: int, item: Item, q: str | None = None):result = {"item_id": item_id, **item.dict()}if q:result.update({"q": q})return result

函数参数 按如下规则进行识别：

• 路径中声明了相同参数的参数，是路径参数
• 类型是（int、float、str、bool 等）单类型的参数，是查询参数
• 类型是 Pydantic 模型的参数，是请求体
• q 默认值是 None ， FastAPI 会把 q 当作可选参数。

六 完整代码示例

from fastapi import FastAPI
from pydantic import BaseModelclass Item(BaseModel):name: strdescription: str | None = Noneprice: floattax: float | None = Noneapp = FastAPI()@app.post("/items/")
async def create_item(item: Item):return item@app.post("/items02/")
async def create_item02(item: Item):item_dict = item.dict()if item.tax:price_with_tax = item.price + item.taxitem_dict.update({"price_with_tax": price_with_tax})return item_dict@app.put("/items03/{item_id}")
async def update_item03(item_id: int, item: Item):return {"item_id": item_id, **item.dict()}@app.put("/items04/{item_id}")
async def update_item04(item_id: int, item: Item, q: str | None = None):result = {"item_id": item_id, **item.dict()}if q:result.update({"q": q})return result

七 源码地址

详情见：GitHub FastApiProj

引用： FastAPI 文档