一文带你搞懂Python FastAPI中所有核心参数的设置

2025-12-31 08:59:45 作者：曲幽

本文带你一次搞懂 FastAPI 中的所有核心参数类型,从简单的查询字符串,再到处理复杂 JSON 或表单数据的请求体,感兴趣的小伙伴可以了解下

本文带你一次搞懂 FastAPI 中的所有核心参数类型：从简单的查询字符串（?name=value），到定义URL片段的路径参数，再到处理复杂 JSON 或表单数据的请求体。重点深入 Pydantic BaseModel，教你如何用它优雅地定义、验证和组织复杂数据，并自动生成 API 文档。读完你就能清晰地规划 API 的数据接口了。

查询参数与路径参数：地基要打牢

这是两种最基础、最常用的参数，都直接体现在 URL 中。

查询参数（Query Parameters）：跟在 URL 问号?后面，格式为key1=value1&key2=value2。在 FastAPI 中，函数参数不是路径的一部分的，默认就是查询参数。

from fastapi import FastAPI
app = FastAPI()

@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
    # `skip`和`limit`就是查询参数，如：/items/?skip=20&limit=5
    return {"skip": skip, "limit": limit}

使用 skip: int = 0 形式，就定义了带默认值的可选参数。如果没有默认值（如 name: str），它就是必需的查询参数。

路径参数（Path Parameters）：直接是 URL 路径的一部分，用花括号{}声明。通常用于唯一标识资源，比如根据ID获取某篇文章。

@app.get("/items/{item_id}")
async def read_item(item_id: int):  # item_id 是路径参数
    return {"item_id": item_id}

注意它们的顺序！如果把 /items/{item_id} 和 /items/me 两个端点都定义，要把具体的路径（/items/me）放在前面，否则me会被当成item_id的值。

请求体参数：处理复杂数据

当你需要客户端发送较多数据（如创建新文章）时，就需要请求体。FastAPI 用 Body(), Form() 等工具函数来声明。

JSON 请求体（Body）：最常见的 REST API 数据格式。使用 Pydantic 的 BaseModel 是最佳实践（下文详解），也可用 Body() 直接声明多个参数。

from fastapi import Body

@app.put("/items/{item_id}")
async def update_item(
    item_id: int,
    name: str = Body(...),  # Body(...) 表示必需项
    description: str = Body(None)  # Body(None) 表示可选项
):
    return {"item_id": item_id, "name": name, "description": description}

表单数据（Form）：当数据来自 HTML 表单或需要上传文件时使用。如何要上传大文件，需要先安装 python-multipart。

from fastapi import Form

@app.post("/login/")
async def login(username: str = Form(...), password: str = Form(...)):
    return {"username": username}

混合参数：自由组合，各司其职

FastAPI 能智能地区分参数来源，你可以同时使用路径、查询和请求体参数。

from fastapi import Path, Query, Body

@app.put("/mixed-items/{item_id}")
async def update_mixed_item(
    *,
    item_id: int = Path(..., title="商品ID", ge=1),  # 路径参数，>=1
    q: str = Query(None, alias="query-string"),      # 可选查询参数，别名
    item: dict = Body(...)                           # 必需的JSON请求体
):
    results = {"item_id": item_id}
    if q:
        results.update({"q": q})
    results.update({"item": item})
    return results

这里用到了参数校验：ge=1 表示值大于等于1。Query, Path, Body 等函数让声明更明确且功能更强大（如添加描述、别名、校验）。

结构化利器：Pydantic BaseModel

这是 FastAPI 的灵魂特性之一。 BaseModel 让你用 Python 类来定义数据模型，它自动处理数据验证、序列化和文档生成。

from pydantic import BaseModel, EmailStr
from typing import Optional, List

class UserCreate(BaseModel):
    # 必需字段
    username: str
    email: EmailStr  # 内置邮箱格式验证
    # 可选字段，带默认值
    full_name: Optional[str] = None
    # 列表类型
    tags: List[str] = []

@app.post("/users/")
async def create_user(user: UserCreate):  # 一个参数接管整个请求体
    # 直接访问已验证好的数据
    if user.full_name:
        greeting = f"Hello, {user.full_name}!"
    else:
        greeting = f"Hello, {user.username}!"
    return {"message": greeting, "user_info": user.dict()}

BaseModel 的优势：

声明即验证： 字段类型不对、邮箱格式错误等会自动返回 422 错误。
自动文档： Swagger UI 和 ReDoc 会自动显示模型结构和示例。
代码清晰： 数据契约明确，业务逻辑与数据验证分离。
嵌套自由： 模型可以嵌套其他模型，轻松处理复杂数据。

完整代码示例

下面是一个融合了主要参数类型的实战示例，你可以直接复制运行。

from fastapi import FastAPI, Path, Query, Body
from pydantic import BaseModel
from typing import Optional
from datetime import datetime

app = FastAPI(title="参数详解示例")

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float = Body(..., gt=0)
    tax: Optional[float] = None
    tags: list = []

@app.post("/advanced-items/{category}")
async def create_advanced_item(
    category: str = Path(..., description="物品分类"),
    item_id: int = Query(..., ge=1, description="物品ID"),
    q: Optional[str] = Query(None, max_length=50),
    urgent: bool = Query(False),
    item: Item = Body(..., example={  # 为文档提供示例
        "name": "Foo",
        "price": 50.5,
        "tags": ["cool", "new"]
    })
):
    """创建新物品的复杂端点"""
    total = item.price + (item.tax if item.tax else 0)
    result = {
        "category": category,
        "item_id": item_id,
        "query_string": q,
        "urgent": urgent,
        "item_name": item.name,
        "total_price": total,
        "created_at": datetime.now().isoformat()
    }
    return result

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

运行后，访问 http://127.0.0.1:8000/docs，你将看到一个功能齐全的交互式 API 文档，所有参数和模型都清晰可见。

到此这篇关于一文带你搞懂Python FastAPI中所有核心参数的设置的文章就介绍到这了,更多相关Python FastAPI参数内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！