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

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

文章目录

FastAPI 请求体解析：基础概念与综合应用
- - 一基础概念
  - 二编辑器支持
  - 三使用模型
  - 四请求体 + 路径参数
  - 五请求体 + 路径参数 + 查询参数
  - 六完整代码示例
  - 七源码地址

示例使用 Python 版本为 Python 3.10.15 。

一基础概念

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

from fastapi import FastAPI
from pydantic import BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = 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.tax
        item_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 BaseModel


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None


app = 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.tax
        item_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