在 FastAPI 中，路径参数、查询参数和请求体参数是构建 API 的三大核心要素。掌握它们的用法，能让你快速设计出规范、易用的接口。本文将结合代码示例，从基础到进阶逐一剖析，并扩展实用知识点，助你学以致用。

一、路径参数（Path Parameters）

路径参数是 URL 路径的一部分，用于标识资源的唯一 ID 或分类。例如 /users/{user_id} 中的 user_id 就是路径参数。

基础用法

from fastapi import FastAPI

app = FastAPI()

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    return {"user_id": user_id}

代码解释：

• @app.get("/users/{user_id}")：定义 GET 请求，路径中用 {} 包裹动态参数 user_id。
• user_id: int：函数参数接收路径参数，类型提示 int 有两个作用：
  1. 自动将 URL 中的字符串转换为整数（如 "123" → 123）；
  2. 自动验证类型，若传入非整数（如 /users/abc），会返回 422 Unprocessable Entity 错误。

关键注意点：路径顺序

当存在固定路径和动态路径时，固定路径必须放在动态路径前面，否则会被动态路径优先匹配。

# 正确：固定路径 /users/me 放在前面
@app.get("/users/me")
async def get_current_user():
    return {"user_id": "current user"}

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    return {"user_id": user_id}

二、查询参数（Query Parameters）

查询参数是 URL 中 ? 后面的键值对，用于过滤、分页等场景。例如 /items/?page=2&size=20 中的 page 和 size。

基础用法：带默认值

@app.get("/items/")
async def get_items(page: int = 1, size: int = 10):
    return {"page": page, "size": size}

代码解释：

• 路径中没有 {}，因此 page 和 size 是查询参数。
• 默认值 =1 和 =10：表示这两个参数是可选的。若不传，默认返回第 1 页，每页 10 条。
• 访问示例：/items/?page=3&size=15 → 返回 {"page": 3, "size": 15}。

进阶用法：必填与可选参数

• 无默认值 → 必填：若参数没有默认值（如 keyword: str），则必须在 URL 中传入，否则报错。
• Optional → 可选：用 typing.Optional 标记参数，允许不传（值为 None）。

from typing import Optional

@app.get("/items/")
async def get_items(
    page: int = 1, 
    size: int = 10, 
    keyword: Optional[str] = None  # 可选参数
):
    return {"page": page, "size": size, "keyword": keyword}

三、请求体参数（Request Body）

请求体用于接收客户端发送的 JSON 数据（如创建、更新资源时的表单数据）。FastAPI 结合 Pydantic 实现数据解析和验证。

基础用法：Pydantic 模型

首先定义一个 Pydantic 模型（继承 BaseModel），描述请求体的字段和类型：

from pydantic import BaseModel
from typing import Optional

# 定义请求体模型
class ItemCreate(BaseModel):
    name: str          # 必填字段
    price: float       # 必填字段
    description: Optional[str] = None  # 可选字段（默认 None）

@app.post("/items/")
async def create_item(item: ItemCreate):
    return {
        "name": item.name,
        "price": item.price,
        "description": item.description
    }

代码解释：

• ItemCreate 模型：
  • 字段 name（字符串）和 price（浮点数）无默认值 → 必填；
  • description 用 Optional[str] 且默认 None → 可选。
• item: ItemCreate：函数参数接收请求体，FastAPI 会自动：
  1. 从请求中读取 JSON 数据；
  2. 解析为 ItemCreate 对象；
  3. 验证数据类型（如 price 传字符串会报错）。

请求示例（JSON 格式）：

json

{
  "name": "Apple",
  "price": 5.5
}

进阶用法：多个请求体参数

若需要同时接收多个模型（或单个字段），可直接在函数中定义多个参数：

class User(BaseModel):
    username: str
    password: str

@app.post("/items/")
async def create_item(item: ItemCreate, user: User):
    return {"item": item, "user": user}

请求示例：

json

{
  "item": {"name": "Apple", "price": 5.5},
  "user": {"username": "test", "password": "123"}
}

四、扩展：常用进阶知识点

掌握基础后，以下进阶技巧能让你的 API 更健壮、更易用。

1. 参数验证：Query 和 Path

用 Query（查询参数）和 Path（路径参数）添加更精细的验证规则（如长度、范围、正则）。

from fastapi import Query, Path

@app.get("/items/{item_id}")
async def get_item(
    # 路径参数：必填，且 >= 1
    item_id: int = Path(..., title="Item ID", ge=1),
    # 查询参数：可选，长度 3-50，且匹配正则
    q: str = Query(None, min_length=3, max_length=50, regex="^fixedquery$"),
    # 查询参数：必填，且 > 0
    price: float = Query(..., gt=0, description="Price must be positive")
):
    return {"item_id": item_id, "q": q, "price": price}

关键验证参数：

• ...：表示必填（无默认值）；
• ge/gt：数值 >= / > 某个值；
• le/lt：数值 <= / < 某个值；
• min_length/max_length：字符串长度范围；
• regex：正则表达式匹配。

2. Pydantic 模型进阶

（1）字段验证：Field（请求体参数）

用 Field 为模型字段添加验证和描述（类似 Query/Path）：

from pydantic import Field

class ItemCreate(BaseModel):
    name: str = Field(..., min_length=2, max_length=50, description="Item name")
    price: float = Field(..., gt=0, description="Price must be positive")
    description: Optional[str] = Field(None, max_length=200, description="Optional description")

（2）嵌套模型

当请求体包含复杂结构时，可嵌套使用 Pydantic 模型：

class Category(BaseModel):
    id: int
    name: str

class ItemCreate(BaseModel):
    name: str
    price: float
    category: Category  # 嵌套 Category 模型

请求示例：

json

{
  "name": "Apple",
  "price": 5.5,
  "category": {"id": 1, "name": "Fruit"}
}

3. 依赖注入：Depends

当多个路由需要复用相同的参数或逻辑时，用 Depends 实现依赖注入，减少代码重复。

示例：复用分页参数

from fastapi import Depends

# 定义依赖函数：封装分页和关键词参数
async def common_parameters(
    page: int = 1, 
    size: int = 10, 
    keyword: Optional[str] = None
):
    return {"page": page, "size": size, "keyword": keyword}

# 在路由中注入依赖
@app.get("/items/")
async def get_items(commons: dict = Depends(common_parameters)):
    return commons

@app.get("/users/")
async def get_users(commons: dict = Depends(common_parameters)):
    return commons

代码解释：

• common_parameters 是一个依赖函数，定义了通用的查询参数；
• 路由函数通过 Depends(common_parameters) 注入依赖，自动接收函数返回的字典；
• 多个路由可复用同一套逻辑，无需重复定义参数。

五、总结与实践建议

1. 路径参数：用于资源标识，注意路径顺序；
2. 查询参数：用于过滤、分页，结合默认值和 Optional 控制必填性；
3. 请求体参数：用 Pydantic 模型解析 JSON，自动验证数据；
4. 进阶技巧：用 Query/Path/Field 做参数验证，嵌套模型处理复杂结构，Depends 复用逻辑。