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）進一步調試和優化接口。