路徑參數(shù)和查詢參數(shù)同名？這個坑 FastAPI 里你得避！
作者：Ss肥魚
在使用 FastAPI 編寫接口時，你有沒有遇到過這樣的需求：接口路徑中帶有 item_id，但前端也傳了一個同名的查詢參數(shù) item_id?
在使用 FastAPI 編寫接口時，你有沒有遇到過這樣的需求：
接口路徑中帶有 item_id，但前端也傳了一個同名的查詢參數(shù) item_id？
例如，請求是這樣的：
GET /items/123?item_id=abc乍一看沒啥問題，路徑參數(shù)是 123，查詢參數(shù)是 abc，看著分工明確，但你一寫代碼就報錯了！
典型錯誤寫法
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(item_id: str, item_id: str = Query(...)):
return {"item_id": item_id}運行后 FastAPI 報錯：
SyntaxError: duplicate argument 'item_id' in function definition原因很簡單：Python 函數(shù)參數(shù)不能重復命名。
正確寫法一：使用別名 alias 來區(qū)分
FastAPI 提供了 alias 參數(shù)來幫你實現(xiàn)“查詢參數(shù)的字段名和接收變量名不同”的功能。
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/{item_id}")
async def read_item(
item_id: str, # 路徑參數(shù)
q: str = Query(None, alias="item_id") # 查詢參數(shù)：仍叫 item_id，但接收為 q
):
return {
"path_param": item_id,
"query_param": q
}測試訪問：
GET /items/123?item_id=abc返回結(jié)果：
{
"path_param": "123",
"query_param": "abc"
}完美分離！
正確寫法二：直接改查詢參數(shù)名
如果你對參數(shù)命名沒有執(zhí)念，可以直接改掉查詢參數(shù)的名字。
@app.get("/items/{item_id}")
async def read_item(item_id: str, filter_id: str = Query(None)):
return {
"path_id": item_id,
"query_filter_id": filter_id
}然后前端傳參：
GET /items/123?filter_id=abc這樣也可以避免沖突。
實戰(zhàn)建議
(1) 路徑參數(shù)優(yōu)先遵循 REST 設計，保持不變
如 /users/{user_id}/posts/{post_id} 是很常見的路徑設計
(2) 查詢參數(shù)可以靈活重命名
使用 alias 保持兼容性，又能避免變量名沖突
(3) 注意 Path / Query / Body 等參數(shù)的接收優(yōu)先級不同
為什么這個細節(jié)值得說？
通過掌握 alias 的用法，你可以：
- 兼容前后端已有設計
- 避免內(nèi)部變量名沖突
- 寫出結(jié)構(gòu)清晰、功能明確的接口邏輯
責任編輯：趙寧寧
來源：
Ssoul肥魚
