FastAPI 偵錯技巧 (Debugging)

開發過程中，遇到 Bug 是家常便飯。雖然 print() 大法很好用，但學會使用 IDE 的 Debugger (偵錯器) 能讓你更有效率地找出問題根源。

由於 FastAPI只是一個標準的 Python 程式，你可以使用任何你習慣的 Python IDE 進行偵錯。

為何不能直接 Debug uvicorn 指令？

通常我們啟動伺服器是用 uvicorn main:app --reload 或現代的 fastapi dev。這些指令會啟動一個 Process 監控檔案變更，並啟動另一個 subprocess 執行你的 App。這會讓 IDE 的 Debugger 很難直接 attach 到正確的 Process 上。

解決方案：用 Python 啟動 Uvicorn

最簡單的方法是建立一個 Python 腳本來啟動 Uvicorn，這樣你就在執行一個普通的 Python 程式，IDE 就能輕鬆介入了。

在你的 main.py (或其他入口檔案) 的最後面加上：

import uvicorn
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    a = "a"
    b = "b" + a # 在這裡設中斷點
    return {"hello": b}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

現在，你可以直接在 IDE 中「執行」或是「偵錯 (Debug)」這個 main.py 檔案。

VS Code 設定

1. 開啟 VS Code 的 "Run and Debug" 面板 (左側蟲子圖示)。
2. 點擊 "create a launch.json file"。
3. 選擇 "Python"。
4. 選擇 "Python File" (Debug the currently active Python file)。

現在打開 main.py，在你想觀察的行號左側點一下設定紅點 (Breakpoint)，然後按 F5 (Start Debugging)。

當程式執行到該行時，會暫停下來，你可以查看當前的變數值 (a, b)，或是單步執行 (Step Over/Step Into)。

PyCharm 設定

1. 在 main.py 視窗中，右鍵點擊。
2. 選擇 "Debug 'main'"。
3. 一樣在行號旁設定中斷點。
4. 發送請求觸發該路由，PyCharm 就會停在中斷點。

這對非同步 (Async) 程式碼有用嗎？

有用！ 現代的 IDE (VS Code, PyCharm) 對 async/await 的偵錯支援已經非常完善。你可以像偵錯同步程式碼一樣偵錯非同步函數。

總結

• 不要直接 Debug uvicorn 命令行指令。
• 在程式碼中使用 uvicorn.run() 啟動 App。
• 像 Debug 普通 Python Script 一樣 Debug FastAPI。
• 善用中斷點來檢查變數狀態，比 print 更快更準。