FastAPI路由模块化与APIRouter

引言：为什么需要路由模块化？

在FastAPI开发中，当项目变得复杂时，将所有路由都放在一个文件中会导致代码难以管理和维护。路由模块化通过将相关的路由分组到不同的模块中，可以提高代码的可读性、可重用性和扩展性。FastAPI的APIRouter是实现这一目标的强大工具，它允许您像组织Python模块一样组织API路由。

什么是APIRouter？

APIRouter是FastAPI中一个核心类，用于创建独立的路由组。您可以将其视为一个子应用，它可以定义自己的路由、依赖项、响应模型等，然后将其集成到主应用中。这使得代码结构更加清晰，便于团队协作和大型项目开发。

如何使用APIRouter

1. 导入APIRouter

首先，确保您已安装FastAPI。在代码中，从fastapi导入APIRouter。

from fastapi import APIRouter

2. 创建APIRouter实例

创建一个APIRouter实例，可以为其指定前缀和标签，以帮助组织路由。

router = APIRouter(
    prefix="/users",  # 所有路由都以"/users"开头
    tags=["users"],   # 在API文档中分组显示
)

3. 定义路由

在路由器上定义路由，就像在主应用中使用FastAPI()实例一样。

@router.get("/")
async def get_users():
    return {"message": "返回用户列表"}

@router.get("/{user_id}")
async def get_user(user_id: int):
    return {"message": f"获取用户 {user_id}"}

4. 将路由器集成到主应用

在主应用中，使用include_router方法将路由器添加进来。

from fastapi import FastAPI

app = FastAPI()

# 导入路由器模块
app.include_router(router)

示例：模块化路由结构

假设我们有一个简单的用户管理系统，可以将路由模块化为不同的文件。

项目结构

myapp/
  main.py          # 主应用文件
  routers/
    users.py       # 用户相关路由
    items.py       # 物品相关路由

users.py（路由器文件）

from fastapi import APIRouter

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/")
async def read_users():
    return [{"user_id": 1}, {"user_id": 2}]

@router.post("/")
async def create_user():
    return {"message": "用户已创建"}

items.py（另一个路由器文件）

from fastapi import APIRouter

router = APIRouter(prefix="/items", tags=["items"])

@router.get("/")
async def read_items():
    return [{"item_id": "foo"}, {"item_id": "bar"}]

main.py（主应用）

from fastapi import FastAPI
from routers import users, items  # 导入路由器

app = FastAPI()

# 集成路由器
app.include_router(users.router)
app.include_router(items.router)

@app.get("/")
async def root():
    return {"message": "欢迎使用FastAPI"}

运行uvicorn main:app --reload，您的API将具有以下路由：

• / - 根路由
• /users/ - 获取用户列表
• /users/（POST）- 创建用户
• /items/ - 获取物品列表

在Swagger UI（http://127.0.0.1:8000/docs）中，您会看到路由被分组到"users"和"items"标签下。

高级用法

1. 嵌套路由

您可以使用多个路由器来创建更复杂的结构。例如，为管理员功能创建子路由器。

# routers/admin.py
from fastapi import APIRouter

admin_router = APIRouter(prefix="/admin", tags=["admin"])

@admin_router.get("/")
async def admin_panel():
    return {"message": "管理员面板"}

然后，在主应用中包含它。

2. 依赖注入

路由器可以定义自己的依赖项，应用于其所有路由。

from fastapi import Depends, APIRouter

router = APIRouter(prefix="/secured", tags=["secured"])

def get_current_user():
    # 假设实现认证逻辑
    return {"username": "testuser"}

@router.get("/")
async def secured_route(user: dict = Depends(get_current_user)):
    return {"message": f"欢迎, {user['username']}!"}

3. 重用路由器和前缀

通过prefix参数，您可以轻松地重写路由器前缀，例如在测试或部署时。

app.include_router(router, prefix="/api/v1")  # 所有路由以"/api/v1"开头

总结

使用APIRouter实现路由模块化是FastAPI中的最佳实践之一。它帮助您：

• 组织代码：将相关路由分组，便于维护。
• 提高可重用性：路由器可以轻松导入和集成到不同项目中。
• 增强可读性：清晰的模块结构使API文档更友好。
• 支持大型项目：适用于团队协作和扩展功能。

开始模块化您的FastAPI项目，让开发过程更加高效和有条不紊！

注意：本教程基于FastAPI官方文档和实践经验编写，适合初学者快速上手。如果您有更多问题，建议参考FastAPI官方文档或参与社区讨论。