FastAPI 路由分發詳解：模塊化項目結構優秀實踐
作者：Ss肥魚
模塊化路由分發，是構建大型 FastAPI 項目的基礎。如果你還在 main.py 里堆代碼，是時候重構你的接口結構了。?
在開發 FastAPI 項目時，隨著業務增長，main.py 中的接口代碼可能會越來越多，變得難以維護。為了保持清晰的結構，我們需要對路由進行模塊化拆分和分發。
本篇文章將帶你了解：
- 路由的基本注冊方式
- 如何將不同模塊的接口拆分到子文件中
- 如何組織大型項目結構
- 路由標簽與接口文檔分組展示
1. FastAPI 中的基礎路由注冊
# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def index():
return {"msg": "Hello World"}
@app.get("/users")
def list_users():
return [{"id": 1, "name": "張三"}]這種方式在項目初期很簡單，但后期業務增加就會導致 main.py 冗長。
2. 使用 APIRouter 模塊化管理接口
FastAPI 提供了 fastapi.APIRouter，可以將路由分散到多個模塊，然后在 main.py 中統一導入。
第一步：創建一個用戶模塊 user.py
# app/routers/user.py
from fastapi import APIRouter
router = APIRouter(prefix="/users", tags=["用戶模塊"])
@router.get("/")
def list_users():
return [{"id": 1, "name": "張三"}]
@router.get("/{user_id}")
def get_user(user_id: int):
return {"id": user_id, "name": "張三"}- prefix：表示該模塊下的所有路由統一前綴，如 /users
- tags：在 Swagger 文檔中對接口進行分組展示
第二步：在 main.py 中引入路由模塊
# main.py
from fastapi import FastAPI
from app.routers import user # 導入自定義路由模塊
app = FastAPI()
app.include_router(user.router) # 注冊用戶模塊路由3. 多模塊項目結構推薦
你可以按功能劃分模塊，例如：
project/
├── app/
│ ├── main.py
│ ├── routers/
│ │ ├── __init__.py
│ │ ├── user.py
│ │ ├── article.py
│ │ └── auth.py
│ ├── models/
│ ├── schemas/
│ └── services/- routers/：接口路由
- models/：數據庫模型
- schemas/：請求/響應模型
- services/：業務邏輯層
每個功能模塊都使用 APIRouter 創建并在 main.py 中注冊。
4. 自動導入多個模塊（可選）
為了避免在 main.py 手動 include_router 太多次，也可以在 routers/__init__.py 中統一注冊：
# routers/__init__.py
from .user import router as user_router
from .article import router as article_router
from .auth import router as auth_router
routers = [user_router, article_router, auth_router]然后 main.py 中寫：
from fastapi import FastAPI
from app.routers import routers
app = FastAPI()
for router in routers:
app.include_router(router)5. 效果展示
啟動項目訪問http://localhost:8000/docs你會看到接口被分組展示，清晰又美觀。
6. 總結
要點 | 描述 |
APIRouter | 拆分接口模塊 |
prefix | 路由前綴，統一歸類 |
tags | 分組展示文檔 |
include_router | 注冊路由模塊 |
模塊化目錄結構 | 更清晰、可維護性強 |
模塊化路由分發，是構建大型 FastAPI 項目的基礎。如果你還在 main.py 里堆代碼，是時候重構你的接口結構了。
責任編輯：趙寧寧
來源：
Ssoul肥魚
