2.Query_String.md
查詢字串參數是 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 機制可提升程式的清晰度與安全性，適合撰寫可維護性高的服務端程式碼。
Last updated