FastAPI 路由详解：路径参数、查询参数、请求体，一篇掌握！
你是否曾在编写接口时对参数处理感到迷糊？
路径参数怎么写？查询参数和请求体参数有啥区别？怎么自动类型校验、生成文档？这篇文章将带你全面掌握 FastAPI 中最常用的三种参数类型，配合 Pydantic 验证，轻松构建高质量 API！
路径参数出现在 URL 中，例如 /users/{user_id}。
复制
from fastapi import FastAPI
app = FastAPI()
@app.get("/users/{user_id}")
def get_user(user_id: int):
return {"user_id": user_id}1.2.3.4.5.6.7.
访问 /users/123，FastAPI 会自动将 123 转为 int 传入 user_id。
特点：
参数写在 URL 路径中自动类型转换常用于资源定位（如用户 ID）查询参数（Query Parameters）查询参数通过 URL ? 后的键值对传递，例如 /search?q=fastapi&limit=10。
复制
@app.get("/search")
def search(q: str, limit: int = 10):
return {"query": q, "limit": limit}1.2.3.
访问 /search?q=fastapi&limit=5 返回：
复制
{"query": "fastapi", "limit": 5}1.
特点：
传参方式灵活，可设置默认值自动类型校验、自动文档支持常用于分页、筛选、搜索请求体参数（Request Body）当你需要传递 JSON 对象等复杂结构，就要用请求体参数，并结合 Pydantic 定义模型。
步骤一：定义数据模型
复制
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
tags: list[str] = []1.2.3.4.5.6.
步骤二：接收请求体
复制
@app.post("/items/")
def create_item(item: Item):
return item1.2.3.
发送请求：
复制
POST /items/
{
"name": "iPhone 15",
"price": 999.9,
"tags": ["phone", "apple"]
}1.2.3.4.5.6.
FastAPI 会：
自动将 JSON 转换为对象自动校验字段自动生成 API 文档混合使用（路径 + 查询 + 请求体）三种参数可以组合使用：
复制
from typing import Union
@app.put("/items/{item_id}")
def update_item(
item_id: int,
q: Union[str, None] = None,
item: Item = None
):
return {
"item_id": item_id,
"q": q,
"item": item
}1.2.3.4.5.6.7.8.9.10.11.12.13.
FastAPI 支持通过 Query 和 Path 设置限制和文档描述：
复制
from fastapi import Query, Path
@app.get("/products/{product_id}")
def get_product(
product_id: int = Path(..., title="产品 ID", ge=1),
keyword: str = Query(None, max_length=20, description="搜索关键词")
):
return {"product_id": product_id, "keyword": keyword}1.2.3.4.5.6.7.8.
支持的验证包括：
是否必填（...）数值范围（ge=1）字符长度（max_length）自动展示在 Swagger 文档中总结类型
来源
适用场景
特点
路径参数
/users/{id}
标识资源
自动转换类型、资源定位
查询参数
?q=xxx&limit=1
筛选分页搜索
可选默认值、自动文档
请求体参数
JSON 请求体
提交复杂结构数据
使用 Pydantic 模型验证解析
FastAPI 的参数处理不仅强大，还智能、自动、文档友好，大大提升开发体验和效率！
THE END
