FastAPI参数详解：路径参数、查询参数与请求体

在开始介绍FastAPI的参数之前，我们先来简单了解一下FastAPI。FastAPI是一个高性能、易于使用的Python Web框架，它支持自动生成API文档，并且对参数类型、数据验证等有很好的支持。在开发API接口时，参数的传递和处理是核心环节，常见的参数类型包括路径参数、查询参数和请求体。本文将针对这三种参数进行详细讲解，帮助初学者快速掌握它们的使用方法。

一、路径参数（Path Parameters）¶

路径参数是指在URL路径中直接作为参数的部分，例如访问/items/42时，42就是路径参数，用于标识具体的资源（如ID为42的商品）。

定义路径参数¶

在FastAPI中，通过在接口路径中使用{参数名}定义路径参数，然后在函数参数中声明该参数的类型。FastAPI会自动从URL路径中提取对应的值，并进行类型检查和转换。

示例代码：

from fastapi import FastAPI

app = FastAPI()

# 定义路径参数item_id（类型为int）
@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id, "message": "This is the item details"}

当访问/items/42时，接口会返回{"item_id": 42, "message": "This is the item details"}。如果访问/items/abc（非整数），FastAPI会自动返回类型错误。

关键点¶

• 格式：路径参数用{参数名}包裹，必须与函数参数名一致。
• 类型自动转换：FastAPI会自动将URL中的字符串参数转换为声明的类型（如int会自动将字符串转为整数）。
• 多路径参数：支持多个路径参数，例如/users/{user_id}/orders/{order_id}：

  @app.get("/users/{user_id}/orders/{order_id}")
  def read_user_order(user_id: int, order_id: int):
      return {"user_id": user_id, "order_id": order_id}

二、查询参数（Query Parameters）¶

查询参数是在URL问号?后以key=value形式传递的参数，常用于过滤、分页等场景（如/items/?item_id=42&q=test中的item_id和q）。

定义查询参数¶

查询参数的定义方式与普通函数参数类似，直接在接口函数中声明，FastAPI会自动从URL查询字符串中提取值。

示例代码：

from fastapi import FastAPI

app = FastAPI()

# 定义可选查询参数（带默认值None）
@app.get("/items/")
def read_items(item_id: int = None, q: str = None):
    return {"item_id": item_id, "q": q}

• 访问/items/?item_id=42&q=test，返回{"item_id": 42, "q": "test"}。
• 若参数没有默认值（如item_id: int），则必须在URL中传递，否则返回错误。

关键点¶

• 默认值与可选性：设置默认值（如item_id: int = None）表示参数可选，无默认值则为必传。
• 类型自动识别：FastAPI会根据参数声明的类型自动转换（如int会将字符串转为整数，失败则报错）。
• 列表查询参数：支持列表格式（如/items/?tags=python&tags=fastapi），FastAPI会自动解析为列表["python", "fastapi"]。

三、请求体（Request Body）¶

请求体是在POST、PUT等请求中，通过请求体（而非URL）传递的复杂数据，通常以JSON格式发送。适合传递多个字段的数据（如创建商品时的名称、价格、描述）。

在FastAPI中，请求体需要通过Pydantic模型定义数据结构，FastAPI结合Pydantic自动解析和验证数据。

定义请求体¶

1. 导入Pydantic模型：from pydantic import BaseModel
2. 定义模型：继承BaseModel并声明字段。
3. 在接口函数中使用模型作为参数，FastAPI会自动解析请求体并验证数据。

示例代码：

from fastapi import FastAPI
from pydantic import BaseModel  # 导入Pydantic基础模型

app = FastAPI()

# 定义请求体模型（商品结构）
class Item(BaseModel):
    name: str
    price: float
    description: str = None  # 可选字段，默认值为None

# 使用模型接收请求体
@app.post("/items/")
def create_item(item: Item):
    return {"item_name": item.name, "item_price": item.price}

发送POST请求到/items/，请求体为：

{
  "name": "Python Book",
  "price": 29.99,
  "description": "A Python programming book"
}

FastAPI会自动解析为Item对象，并验证字段类型（如price必须为浮点数）。

关键点¶

• 数据验证：Pydantic模型自动验证数据类型和格式，错误时返回422 Validation Error。
• 嵌套模型：支持复杂结构（如嵌套对象），例如：

  class User(BaseModel):
      name: str
      address: dict  # 嵌套字典

• 适用场景：复杂数据传递（如创建/更新资源），结构清晰且便于扩展。

四、参数使用场景对比¶

五、常见问题与注意事项¶

1. 参数顺序：路径参数 > 查询参数 > 请求体，无需显式排序（FastAPI自动识别）。
2. 必选与可选：无默认值的参数（如item_id: int）必须传递，有默认值（如q: str = None）可选。
3. 自动错误处理：类型错误、参数缺失等会自动返回422 Validation Error，无需手动处理。

掌握这三种参数的使用，你就能构建基础且功能完整的API接口了。后续可结合FastAPI的自动文档（访问/docs或/redoc）进一步调试和优化接口。