FastAPI中的APIRouter

最近在学习FastAPI中一直被APIrouter搞不懂，通过理解学习给大家分享一下心得：

在 FastAPI 中，APIRouter 是用来「模块化组织路由」的工具，你可以把它理解为一个 「子应用」或「路由分组器」。

它的核心作用是帮你把原本写在 main.py 里的大量接口，拆分到不同的文件中，最后再集中挂载到主应用上，让项目结构更清晰、易维护。

为什么要用 APIRouter？（举个对比例子）

假设你在做一个 AI Agent 平台，有「用户管理」和「Agent 管理」两组接口：

❌ 不用 APIRouter（所有代码挤在 main.py）

# main.py
from fastapi import FastAPI

app = FastAPI()

# 用户相关接口（一堆）
@app.post("/users/login")
def login(): pass

@app.get("/users/info")
def get_user_info(): pass

# Agent 相关接口（又一堆）
@app.post("/agents/create")
def create_agent(): pass

@app.get("/agents/list")
def list_agents(): pass

→ 项目越大，main.py 越臃肿，找接口、改代码都很痛苦。

✅ 用 APIRouter（文件分离）

你可以把代码拆成 3 个文件：

1. routers/user.py（用户模块）

from fastapi import APIRouter

# 创建一个用户路由对象
user_router = APIRouter(prefix="/users", tags=["用户管理"])

@user_router.post("/login")
def login():
return {"msg": "登录成功"}

@user_router.get("/info")
def get_user_info():
return {"name": "张三"}

2. routers/agent.py（Agent 模块）

from fastapi import APIRouter

# 创建一个 Agent 路由对象
agent_router = APIRouter(prefix="/agents", tags=["Agent管理"])

@agent_router.post("/create")
def create_agent():
return {"msg": "Agent创建成功"}

@agent_router.get("/list")
def list_agents():
return {"agents": ["Agent1", "Agent2"]}

3. main.py（主应用，只负责挂载路由）

from fastapi import FastAPI
from routers.user import user_router # 导入子路由
from routers.agent import agent_router

app = FastAPI()

# 把路由「挂载」到主应用上
app.include_router(user_router)
app.include_router(agent_router)

APIRouter 的 3 个核心优势

总结

APIRouter 就像一个「路由收纳盒」：

• 你可以把不同功能的接口放进不同的「收纳盒」（APIRouter 对象）；
• 最后在 main.py 里把这些「收纳盒」统一放到「大柜子」（主应用 app）里。