请求体

FastAPI 使用请求体从客户端（例如浏览器）向 API 发送数据。请求体是客户端发送给 API 的数据。响应体是 API 发送给客户端的数据。

使用 Pydantic 模型声明请求体，能充分利用它的功能和优点

from fastapi import FastAPI
from pydantic import BaseModel # 导入BaseModel 用于数据模型定义class Item(BaseModel):# 把数据模型声明为继承BaseModel的类name: strdescription: str | None = Noneprice: floattax: float | None = Noneapp = FastAPI()@app.post("/items/")
async def create_item(item: Item):return item

FastAPI 支持同时声明请求体、路径参数和查询参数。

查询参数和字符串校验

可以为查询参数添加额外的约束条件
使用Query明确告诉 FastAPI 这是一个查询参数，并且提供参数的额外配置和验证规则

Query常用参数：

Query(default=None,           # 默认值max_length=50,         # 最大长度min_length=1,          # 最小长度regex="^[a-zA-Z]+$",   # 正则表达式验证description="搜索关键词", # 参数描述example="hello"        # 示例值
)

from fastapi import FastAPI, Query # 导入Queryapp = FastAPI()@app.get("/items")
# 将 Query 用作查询参数的默认值，并将它的 max_length 参数设置为 50
async def read_items(q : str | None = Query(default="hey", max_length=50, min_length=1, regex="^hey+")):results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}if q:results.update({"q": q})return results

多个查询参数

当你使用 Query 显式地定义查询参数时，你还可以声明它去接收一组值，或换句话来说，接收多个值。

from fastapi import FastAPI, Query # 导入Queryapp = FastAPI()@app.get("/items")
# 将 Query 用作查询参数的默认值，并将它的 max_length 参数设置为 50
async def read_items(q : list[str] | None = Query(default=None)):query_items = {"q" : q}return query_items

访问：http://localhost:8000/items?q=foo&q=bar
结果：

还可以定义默认的列表值

async def read_items(q : list[str] | None = Query(default=["1", "2"])):

还可以添加title、description添加参数的元数据

async def read_items(q : list[str] | None = Query(default=["1", "2"], title="q query", description="description of q")):

参数别名

假设你想要查询参数为 item-query，但是 item-query 不是一个有效的 Python 变量名称。这时你可以用 alias 参数声明一个别名，该别名将用于在 URL 中查找查询参数值

from fastapi import FastAPI, Query # 导入Queryapp = FastAPI()@app.get("/items")
# 将 Query 用作查询参数的默认值，并将它的 max_length 参数设置为 50
async def read_items(q : str | None = Query(default=None, max_length=50, alias="item-query")):results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}if q:results.update({"q": q})return results

弃用参数

将参数 deprecated=True 传入 Query，在文档中会标记已弃用

async def read_items(q : str | None = Query(default=None, max_length=50, alias="item-query", deprecated=True)):

路径参数和数值校验

与使用 Query 为查询参数声明更多的校验和元数据的方式相同，你也可以使用 Path 为路径参数声明相同类型的校验和元数据

Annotated 是 Python 中用于添加元数据到类型注解的特殊类型。使用格式为Annotated[类型, 元数据1, 元数据2, …]

路径参数使用Path声明

from fastapi import FastAPI, Query , Path# 导入Path和Query类
from typing import Annotatedapp = FastAPI()@app.get("/items/{item_id}")
# 将 Query 用作查询参数的默认值，并将它的 max_length 参数设置为 50
async def read_items(item_id: Annotated[int, Path(title="The ID of the item to get")],q: Annotated[str | None, Query(max_length=50)] = None):results = {"item_id": item_id}if q:results.update({"q": q})return results

在参数列表前加上*表示其后面的参数必须显式指定

数值约束

可以对数值类型参数约束其范围

• ge: 大于等于
• le: 小于等于
• gt: 大于
• lt: 小于

from fastapi import FastAPI, Pathapp = FastAPI()@app.get("/items/{item_id}")
async def read_items(*, item_id: int = Path(title="The ID of the item to get", ge=1), q: str
):results = {"item_id": item_id}if q:results.update({"q": q})return results