AI智能体项目实战记录（11）：FastAPI 项目路由拆分「主入口 + 多个路由模块」

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

1. 引言

上一篇我们实现了一个简单的 AI 智能问答助手接口，把所有逻辑都写在了一个文件里。但随着项目功能增多——上传文件、下载文件、生成文章等——如果全部堆在 main.py 里，代码会越来越臃肿，难以维护。

这一篇我们借鉴 Spring Boot 的 Controller 思想，把 FastAPI 项目拆分成「主入口 + 多个路由模块」，让每个接口各归其位，路由统一在入口处注册管理。

2. 项目结构设计

我们先规划一下目录结构，模仿 Spring Boot 的 Controller 分层：

project/
├── main.py # 主入口，统一注册路由
├── model_caller.py # 模型调用封装（上一篇已有）
├── routers/
│ ├── __init__.py
│ ├── chat.py # 聊天问答接口
│ ├── file.py # 文件上传/下载接口
│ └── article.py # 文章生成接口

每个 routers/ 下的文件就是一个「Controller」，各自管理自己的接口；main.py 只负责启动服务和挂载路由。

3. 创建路由模块

3.1 聊天路由（chat.py）

把上一篇的聊天接口迁移到独立模块：

# routers/chat.py
from fastapi import APIRouter
from pydantic import BaseModel
from model_caller import call_deepseek_async, call_local_llm, build_prompt

router = APIRouter(prefix="/chat", tags=["聊天"])

class ChatRequest(BaseModel):
question: str
use_deepseek: bool = True # True 用 DeepSeek，False 用本地模型

@router.post("")
async def chat(req: ChatRequest):
prompt = build_prompt(req.question)
if req.use_deepseek:
answer = await call_deepseek_async(prompt)
else:
answer = call_local_llm(prompt)
return {"question": req.question, "answer": answer}

注意这里用了 APIRouter，并设置了 prefix="/chat"，这样接口路径就是 /chat。

3.2 文件路由（file.py）

# routers/file.py
from fastapi import APIRouter, UploadFile, File
from fastapi.responses import FileResponse
import os

router = APIRouter(prefix="/file", tags=["文件"])

UPLOAD_DIR = "uploads"
os.makedirs(UPLOAD_DIR, exist_ok=True)

@router.post("/upload")
async def upload_file(file: UploadFile = File(...)):
file_path = os.path.join(UPLOAD_DIR, file.filename)
with open(file_path, "wb") as f:
f.write(await file.read())
return {"filename": file.filename, "path": file_path}

@router.get("/download/{filename}")
async def download_file(filename: str):
file_path = os.path.join(UPLOAD_DIR, filename)
if not os.path.exists(file_path):
return {"error": "文件不存在"}
return FileResponse(file_path, filename=filename)

3.3 文章生成路由（article.py）

# routers/article.py
from fastapi import APIRouter
from pydantic import BaseModel
from model_caller import call_deepseek_async, build_prompt

router = APIRouter(prefix="/article", tags=["文章"])

class ArticleRequest(BaseModel):
topic: str
length: int = 800

@router.post("/generate")
async def generate_article(req: ArticleRequest):
prompt = build_prompt(f"请写一篇关于{req.topic}的文章，约{req.length}字")
content = await call_deepseek_async(prompt)
return {"topic": req.topic, "content": content}

4. 主入口统一注册路由

现在 main.py 变得非常简洁，只负责创建应用和挂载各个路由模块：

# main.py
from fastapi import FastAPI
from routers import chat, file, article

app = FastAPI(title="AI 智能问答助手")

# 统一注册路由，类似 Spring Boot 装配 Controller
app.include_router(chat.router)
app.include_router(file.router)
app.include_router(article.router)

@app.get("/")
async def root():
return {"message": "服务运行中"}

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

app.include_router() 就是路由注册的核心，把每个模块的 router 挂载到主应用上。

5. 路由前缀与路径对照

注册后，各接口的完整路径如下：

6. 启动与验证

启动服务：

uvicorn main:app –reload

访问 http://localhost:8000/docs 即可看到 Swagger 文档，所有接口按 tags 分组展示，一目了然。

7. 总结

通过 APIRouter + include_router，我们实现了类似 Spring Boot Controller 的路由管理方式：

• 每个业务模块独立成文件，职责清晰；
• 主入口只做路由装配，不再堆业务代码；
• 新增接口只需新建一个路由模块，再在 main.py 里注册一行即可。

后续项目再大，也可以继续按模块拆分，保持代码整洁易维护。