FastAPI -API Router的应用

APIRouter 是 FastAPI 框架中用于模块化组织路由的核心组件。你可以把它理解为一个"子应用"或"路由分组器"。

它的核心作用是帮助你将庞大的 API 接口拆分到不同的文件中进行管理，最后再统一挂载到主应用上，从而让项目结构更清晰、更易于维护。

为什么需要 APIRouter？

想象一下，你正在开发一个大型项目，如果不使用 APIRouter，所有的接口（如用户登录、商品管理、订单处理等）都会堆砌在 main.py 这一个文件中。随着项目扩大，这个文件会变得极其臃肿，查找和修改代码都会变得非常困难。

APIRouter 就像是为你提供了一个个"收纳盒"，让你可以把不同功能的接口分门别类地放进去，最后再把所有"收纳盒"整齐地放进"大柜子"（主应用）里。

使用 APIRouter 的主要优势

• 模块化拆分：将不同功能的接口（如用户、商品、订单）分到不同的文件中，代码结构清晰，符合单一职责原则。
• 统一前缀管理 ：通过 prefix 参数，可以为该组所有接口统一添加 URL 前缀（如 /users），无需在每个接口路径中重复书写。
• 文档自动分组 ：通过 tags 参数，可以让 FastAPI 自动生成的 Swagger 文档（/docs）中的接口按模块分组显示，更易读。
• 模块级依赖注入：可以为整个路由组设置共同的依赖项（如身份验证），避免在每个接口中重复编写相同的逻辑。

如何使用 APIRouter

下面通过一个简单的例子来展示如何使用 APIRouter 来重构代码。

❌ 不使用 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

# 商品相关接口
@app.post("/items/create")
def create_item(): pass

@app.get("/items/list")
def list_items(): pass
# 项目越大，main.py 越臃肿

✅ 使用 APIRouter (文件分离，结构清晰)

你可以将代码拆分成三个文件：

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/item.py (商品模块)

   from fastapi import APIRouter
   
   # 创建一个商品路由对象
   item_router = APIRouter(prefix="/items", tags=["商品管理"])
   
   @item_router.post("/create")
   def create_item():
       return {"msg": "商品创建成功"}
   
   @item_router.get("/list")
   def list_items():
       return {"items": ["商品1", "商品2"]}

3. main.py (主应用，只负责挂载路由)

   from fastapi import FastAPI
   from routers.user import user_router  # 导入用户路由
   from routers.item import item_router   # 导入商品路由
   
   app = FastAPI()
   
   # 把各个模块的路由「挂载」到主应用上
   app.include_router(user_router)
   app.include_router(item_router)

通过这种方式，你的项目结构会变得非常清晰，每个模块都独立在自己的文件中，极大地提升了代码的可读性和可维护性。