在設計API中，肯定會碰到需要傳入參數的時候。

舉個例子，我們使用點餐系統作為範例，實作API時，拿取一張訂單可能會設計為 /order/1 或者是 /order/?id=1 。

前者直接將值放置在路徑中的稱為路徑參數，後者為key-value的集合，位於URL的?後面並以&

隔開，我們稱為查詢參數。

接下來我們接續上一章 HelloWorld 的程式碼繼續使用。

路徑參數

在FastAPI中，你可以使用跟Python f-string 一樣的語法來宣告路徑參數。

@app.get("/orders/{id}")
def get_order(id: int):
    return {"id": id, "name": "My order"}

我們在路徑中宣告要傳入參數 id，並將參數傳遞給 get_order 函式。

在 get_order 函式的輸入定義id的型態為 int，FastAPI會自動幫你驗證輸入的是不是 int。

在文件畫面也會跟你說這個路徑參數需要傳入 int

正確輸入會得到以下 response。

若輸入 int 以外的會發生驗證錯誤。

查詢參數

除了路徑參數以外，在函式中宣告的輸入參數都會被認為是查詢參數。

@app.get("/orders")
def get_order(id: int):
    return {"id": id, "name": "My order"}

我們只定義 get_order 需要一個 int 型態的 id 輸入，這樣便會被自動解析為是要傳入查詢參數。

在API文件中也可以看到確實如我們所要 :

測試看看會獲得以下結果

選填和預設值

由於查詢參數不是API路徑的固定部分，所以可以設置為選填並可有預設值。

@app.get("/orders")
def get_order(id: int = 5):
    return {"id": id, "name": "My order"}

只需要在函式輸入定義好給予的值即可，這裡預設為 5 。

在API文件中可以看到 id 變為選填，且 default value 為 5。

你也可以將一個參數的型態設為 {type} | None 的形式，並將預設值給予 None，以達成選填效果。

@app.get("/orders")
def get_order(id: int = 5, q: str | None = None):
    if q:
        return {"id": id, "name": q}
    return {"id": id, "name": "My order"}

並在程式判斷參數存不存在，以執行對應邏輯。

混合參數使用

FastAPI允許將兩種參數混合使用，只需要宣告定義好即可。

@app.get("/user/{user_id}/order/{order_id}")
def get_user_order(user_id: int, order_id: int, q: str | None = None):
    return {"user_id": user_id, "order_id": order_id, "q": q}

例如以上 user_id, order_id 皆為路徑參數，q 為查詢參數，FastAPI皆可解析的到。

文件中可以看到，被解析分類成我們想要的形式。

小結

透過今天的介紹，大家應該知道如果要實作一個 get 端點時我們要怎麼讓用戶端去輸入我們需要的參數了，FastAPI 在解析路徑和查詢參數的同時還能夠順便驗證資料型別，我覺得這是一個十分便利的事情。

參考資料

路径参数 - FastAPI (tiangolo.com)

查询参数 - FastAPI (tiangolo.com)