FastAPI请求体参数解析：从基础到高级的学习

原创

于 2025-05-16 15:13:46 发布 · 2k 阅读

55 ·

CC 4.0 BY-SA版权

文章标签：

#FastAPI

FastAPI 请求体参数详解

1. 参数类型

FastAPI 中的参数主要分为以下三种类型：

路径参数（Path Parameters）：如果参数出现在路径中，FastAPI 默认将其视为路径参数。
查询参数（Query Parameters）：如果单个参数未在路径中出现，默认会被视为查询参数，即使使用 POST 方法也是如此。
请求体参数（Body Parameters）：如果参数类型是一个 Pydantic 模型，则该参数会被默认视为请求体参数。

2. 单个请求体参数

要将单个参数作为请求体参数，需要使用 Body 显式声明。

from fastapi import Body, FastAPI
from typing import Annotated

app = FastAPI()

@app.post("/items/")
async def read_item(item_id: Annotated[int, Body()]):
    return {"item_id": item_id}

测试方法：

FastAPI 提供的 Docs 界面：在浏览器中访问 /docs，通过界面测试接口。
Requests 库：

import requests

url = 'http://127.0.0.1:8009/items/'
res = requests.put(url, json=5)
print(res.text)  # 输出：{"item_id":5}

3. 多个请求体参数

当有多个请求体参数时，可以将它们嵌套在一个字典中传递。

from fastapi import Body, FastAPI
from typing import Annotated

app = FastAPI()

@app.post("/items/")
async def read_item(item_id: Annotated[int, Body()], name: Annotated[str, Body()]):
    return {"item_id": item_id, "name": name}

测试方法：

Requests 库：

url = 'http://127.0.0.1:8009/items/'
data = {"item_id": 5, "name": "张三"}
res = requests.put(url, json=data)
print(res.text)  # 输出：{"item_id":5,"name":"张三"}

4. Pydantic 模型请求体参数

可以直接将 Pydantic 模型作为请求体参数。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

@app.post("/items/")
async def read_item(item: Item):
    return {"name": item.name, "price": item.price}

测试方法：

Requests 库：

url = 'http://127.0.0.1:8009/items/'
data = {"name": "细胞生物学", "description": "考研书籍", "price": 35.8, "tax": 0.6}
res = requests.post(url, json=data)
print(res.text)  # 输出：{"name":"细胞生物学","price":35.8}

5. 混合使用 Path、Query 和请求体参数

可以同时使用路径参数、查询参数和请求体参数。

from fastapi import Body, FastAPI
from typing import Annotated

app = FastAPI()

@app.post("/items/{name}")
async def read_item(name: str, age: int, item_id: Annotated[int, Body()]):
    return {"name": name, "age": age, "item_id": item_id}

测试方法：

Requests 库：

url = 'http://127.0.0.1:8009/items/张三?age=18'
res = requests.post(url, json=5)
print(res.text)  # 输出：{"name":"张三","age":18,"item_id":5}

6. 多个 Pydantic 模型请求体参数

当函数中有多个 Pydantic 模型参数时，FastAPI 会自动将参数名称作为请求体中的键。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

class User(BaseModel):
    username: str
    full_name: str | None = None

@app.post("/items/")
async def read_item(item: Item, user: User):
    return {"name": item.name, "price": item.price, "user": user}

测试方法：

Requests 库：

url = 'http://127.0.0.1:8009/items/'
data = {
    "item": {"name": "细胞生物学", "description": "考研书籍", "price": 35.8, "tax": 0.6},
    "user": {"username": "张三", "full_name": "张三丰"}
}
res = requests.post(url, json=data)
print(res.text)  # 输出：{"name":"细胞生物学","price":35.8,"user":{"username":"张三","full_name":"张三丰"}}

7. 嵌入单个请求体参数

如果希望将单个 Pydantic 模型参数嵌入到 JSON 的键中，可以使用 Body(embed=True)。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

@app.post("/items/")
async def read_item(item: Item = Body(embed=True)):
    return {"name": item.name, "price": item.price}

测试方法：

Requests 库：

url = 'http://127.0.0.1:8009/items/'
data = {
    "item": {"name": "细胞生物学", "description": "考研书籍", "price": 35.8, "tax": 0.6}
}
res = requests.post(url, json=data)
print(res.text)  # 输出：{"name":"细胞生物学","price":35.8}

8. 总结

路径参数：直接出现在 URL 路径中。
查询参数：通过 URL 的查询字符串传递。
请求体参数：通过 JSON 格式的请求体传递。
Pydantic 模型：可以简化复杂的请求体结构，并提供自动校验功能。
混合使用：可以同时使用路径参数、查询参数和请求体参数。

通过以上内容，可以灵活地处理各种类型的参数，满足不同的 API 需求。

FastAPI 额外参数信息详解

1. 核心概念理解

校验与元数据声明：通过Field在数据模型中定义字段约束条件（如数值范围、字符串长度）和描述信息
文档集成机制：所有声明信息会自动转换为OpenAPI规范，驱动交互式文档生成
作用域区分：
- Query/Path/Body

最低0.47元/天解锁文章