FastAPI 路由分發(fā)詳解：模塊化項(xiàng)目結(jié)構(gòu)優(yōu)秀實(shí)踐
在開發(fā) FastAPI 項(xiàng)目時(shí)，隨著業(yè)務(wù)增長(zhǎng)，main.py 中的接口代碼可能會(huì)越來越多，變得難以維護(hù)。為了保持清晰的結(jié)構(gòu)，我們需要對(duì)路由進(jìn)行模塊化拆分和分發(fā)。
本篇文章將帶你了解：
- 路由的基本注冊(cè)方式
- 如何將不同模塊的接口拆分到子文件中
- 如何組織大型項(xiàng)目結(jié)構(gòu)
- 路由標(biāo)簽與接口文檔分組展示
1. FastAPI 中的基礎(chǔ)路由注冊(cè)
# 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": "張三"}]這種方式在項(xiàng)目初期很簡(jiǎn)單，但后期業(yè)務(wù)增加就會(huì)導(dǎo)致 main.py 冗長(zhǎng)。
2. 使用 APIRouter 模塊化管理接口
FastAPI 提供了 fastapi.APIRouter，可以將路由分散到多個(gè)模塊，然后在 main.py 中統(tǒng)一導(dǎo)入。
第一步：創(chuàng)建一個(gè)用戶模塊 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：表示該模塊下的所有路由統(tǒng)一前綴，如 /users
- tags：在 Swagger 文檔中對(duì)接口進(jìn)行分組展示
第二步：在 main.py 中引入路由模塊
# main.py
from fastapi import FastAPI
from app.routers import user # 導(dǎo)入自定義路由模塊
app = FastAPI()
app.include_router(user.router) # 注冊(cè)用戶模塊路由3. 多模塊項(xiàng)目結(jié)構(gòu)推薦
你可以按功能劃分模塊，例如：
project/
├── app/
│ ├── main.py
│ ├── routers/
│ │ ├── __init__.py
│ │ ├── user.py
│ │ ├── article.py
│ │ └── auth.py
│ ├── models/
│ ├── schemas/
│ └── services/- routers/：接口路由
- models/：數(shù)據(jù)庫(kù)模型
- schemas/：請(qǐng)求/響應(yīng)模型
- services/：業(yè)務(wù)邏輯層
每個(gè)功能模塊都使用 APIRouter 創(chuàng)建并在 main.py 中注冊(cè)。
4. 自動(dòng)導(dǎo)入多個(gè)模塊（可選）
為了避免在 main.py 手動(dòng) include_router 太多次，也可以在 routers/__init__.py 中統(tǒng)一注冊(cè)：
# 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. 效果展示
啟動(dòng)項(xiàng)目訪問http://localhost:8000/docs你會(huì)看到接口被分組展示，清晰又美觀。
6. 總結(jié)
要點(diǎn) | 描述 |
APIRouter | 拆分接口模塊 |
prefix | 路由前綴，統(tǒng)一歸類 |
tags | 分組展示文檔 |
include_router | 注冊(cè)路由模塊 |
模塊化目錄結(jié)構(gòu) | 更清晰、可維護(hù)性強(qiáng) |
模塊化路由分發(fā)，是構(gòu)建大型 FastAPI 項(xiàng)目的基礎(chǔ)。如果你還在 main.py 里堆代碼，是時(shí)候重構(gòu)你的接口結(jié)構(gòu)了。
