【FastAPI 學習筆記 EP.8】APIRouter 路由管理

2025/12/30 更新2025/12/16 發佈閱讀 8 分鐘

這篇文章將教你如何使用 FastAPI 的 APIRouter 將龐大的 API 專案拆分成獨立、好管理的模組。學會 APIRouter 能讓你避免將成百上千行的程式碼全部擠在 main.py 中，這是開發中大型後端系統的必備技能。

什麼是 APIRouter？

APIRouter 是 FastAPI 用來組織和將路徑操作 (Path Operations) 分組的工具。你可以把它想像成公司裡的「部門主管」，而 FastAPI app 是「執行長」。執行長不需要親自處理每一件瑣事，而是將任務指派給各部門主管 (Router)，最後由部門主管統一匯報結果。

APIRouter 基礎概念

1. 建立 Router 實例

你需要先從 fastapi 套件匯入 APIRouter 類別，並建立一個實例物件。這個物件的操作方式與主程式的 app 非常相似。

from fastapi import APIRouter

# 建立一個 router 實例
router = APIRouter()

這段程式碼建立了一個獨立的路由控制器，後續的 API 路徑都會掛載在這個 router 物件上。

2. 使用 Router 定義路徑

在 Router 中定義 API 的方式，是使用 @router.get 或 @router.post 來定義 API，而不是 @app。

# 使用 @router 裝飾器，而不是 @app
@router.get("/users/")
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]

3. 設定前綴 (Prefix) 與標籤 (Tags)

為了避免重複寫同樣的路徑開頭（例如 /users），並讓自動生成的 API 文件分類更清楚，可以在建立 APIRouter 時設定參數。

# 設定所有路徑前綴為 /users，並在文件中歸類為 "Users"
router = APIRouter(
    prefix="/users",
    tags=["Users"]
)

@router.get("/") # 實際路徑會變成 /users/
async def read_users():
    return [{"username": "Rick"}]

4. 註冊到主程式

Router 定義好後，必須使用 app.include_router() 將其加入主程式，否則這些路徑無法被外部訪問。

from fastapi import FastAPI

# 假設上面的 router 定義在 user_router 變數中
app = FastAPI()

app.include_router(router)

APIRouter 實作範例

以下範例將「使用者管理」功能獨立出來的情境，請將程式碼想像為分拆成兩個檔案：users.py (子模組) 與 main.py (主程式)。

├── main.py          # 程式進入點
└── routers          # 存放路由的資料夾
    ├── users.py     # 使用者相關 API

1. 建立 `routers/users.py`

# routers/users.py

from fastapi import APIRouter

# 1. 建立 Router，設定共用前綴與標籤
router = APIRouter(
    prefix="/users",
    tags=["User Management"]
)

# 2. 定義路徑：取得所有使用者
# 實際請求 URL: GET /users/
@router.get("/")
async def get_users():
    return [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]

# 3. 定義路徑：取得特定使用者
# 實際請求 URL: GET /users/me
@router.get("/me")
async def get_current_user():
    return {"id": 1, "name": "Alice", "role": "admin"}

# 4. 定義路徑：取得特定 ID 使用者
# 實際請求 URL: GET /users/{user_id}
@router.get("/{user_id}")
async def get_user_by_id(user_id: int):
    return {"id": user_id, "name": "Guest"}

2. 整合至 `main.py`

# main.py

from fastapi import FastAPI
from routers import users

app = FastAPI()

# 使用 include_router 將子路由註冊到主程式
app.include_router(users.router)

@app.get("/")
async def root():
    return {"message": "Hello World"}

users.py 專注處理使用者邏輯，完全不需要知道 main.py 的存在。main.py 則作為入口，負責組裝所有的 Router。當你啟動伺服器後，訪問 /users/me 就能正確觸發 users.py 中的函式。

常見錯誤與解決方法

1. 忘記在主程式註冊 Router

常常定義了 Router 卻忘記在 main.py 中引用，導致 API 出現 404 Not Found。

# 錯誤範例 (在 main.py 中漏掉)
app = FastAPI()
# 什麼都沒寫，routers/users.py 裡的 API 永遠不會生效

# 正確範例
from routers import users

app = FastAPI()

app.include_router(users.router) # 必須明確加入這行

2. 在子檔案中錯誤使用 app 實例

在路由檔案中習慣性地建立 app = FastAPI()，這是錯誤的，因為這會建立另一個獨立的應用程式，而非主程式的一部分。

# 錯誤範例 (在 routers/users.py 中)
from fastapi import FastAPI

app = FastAPI() # 錯誤！這裡不該建立新的 app

@app.get("/")   # 錯誤！

def read_users(): ...



# 正確範例
from fastapi import APIRouter

router = APIRouter() # 正確：使用 APIRouter

@router.get("/")     # 正確：使用 router 裝飾器

def read_users(): ...