Query String

查詢字串參數是 URL 中 ? 後面的鍵值對組合，常用於前端傳遞資料給後端，例如篩選條件、分頁數字或搜尋關鍵字。

查詢參數格式

基本格式如下：

?key1=value1&key2=value2

範例：

/search?q=fastapi&page=2

代表：搜尋字串為 fastapi，頁數為第 2 頁。

FastAPI 中使用查詢參數

使用查詢參數時，不需要在路由中宣告變數，而是直接於函式參數中設定。

from fastapi import FastAPI

app = FastAPI()

@app.get("/search")
def search(q: str, page: int = 1):
    return {"query": q, "page": page}

呼叫：

http://127.0.0.1:8000/search?q=machine+learning&page=3

預設值與選擇性參數

可以為參數指定預設值，使其變為「非必要參數」。

@app.get("/products")
def list_products(category: str = "all"):
    return {"category": category}

呼叫 /products 將回傳 {"category": "all"}。

多參數處理與類型驗證

FastAPI 自動根據型別進行驗證與轉換，例如：

@app.get("/sum")
def compute_sum(a: int, b: int):
    return {"sum": a + b}

呼叫 /sum?a=10&b=20 → 回傳 {"sum": 30}。如果輸入 /sum?a=ten&b=20 將回傳錯誤。

使用 Annotated 與 Query 進行進階驗證

FastAPI 提供 Annotated 與 Query 搭配使用進行更嚴謹的參數限制與描述。

from fastapi import Query
from typing import Annotated

@app.get("/books")
def read_books(
    keyword: Annotated[str, Query(min_length=3, max_length=20)],
    limit: Annotated[int, Query(ge=1, le=100)] = 10
):
    return {"keyword": keyword, "limit": limit}

說明：

min_length、max_length：限制字串長度
ge（greater or equal）、le（less or equal）：數值範圍限制
可搭配 description="..." 供自動文件顯示

使用 Annotated 與 Path 進行路由參數驗證

from fastapi import Path
from typing import Annotated

@app.get("/users/{user_id}")
def get_user(user_id: Annotated[int, Path(ge=1, le=10000)]):
    return {"user_id": user_id}

說明：

Path(...) 用於限制路由變數的範圍與型別
常用的條件：ge（>=）、le（<=）、description 等

路由參數 vs 查詢參數

路由參數（Path Parameters）：

定義於 URL 路徑中，必須提供，不可省略。

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

呼叫：/users/123 → {"user_id": 123}

路由參數 + 查詢參數同時使用

@app.get("/users/{user_id}/orders")
def user_orders(
    user_id: Annotated[int, Path(ge=1)],
    limit: Annotated[int, Query(ge=1, le=50)] = 10
):
    return {"user": user_id, "limit": limit}

呼叫：/users/42/orders?limit=10 → {"user": 42, "limit": 10}

小結

類型	範例	用途
路由參數	`/item/123`	對應資源主鍵，必要參數
查詢參數	`/search?q=ai&page=2`	選擇性篩選與條件
同時使用	`/user/5/orders?limit=10`	複合資源 + 額外條件
`Annotated` 結合	`Path` / `Query` 進階驗證	提供型別、長度、範圍控制

查詢參數與路由參數是 Web API 的核心資料傳遞方式，使用 FastAPI 的 Annotated 機制可提升程式的清晰度與安全性，適合撰寫可維護性高的服務端程式碼。

FilesExpand file tree

2.Query_String.md

Latest commit

History