FastAPI代码模块化：如何在多文件中使用app装饰器？

核心方案：APIRouter拆分路由 + 事件函数注册 #

FastAPI官方推荐使用APIRouter实现路由模块化拆分，对于@app.on_event这类依赖app实例的操作，无需在子文件中直接使用app装饰器——只需将事件逻辑定义为独立函数，在主文件中通过app.add_event_handler注册即可，既避免循环导入，又不会让主文件臃肿。

1. 目录结构规划 #

按功能模块拆分路由，示例结构：

your_project/
├── main.py
└── routers/
    ├── __init__.py
    └── items.py  # 对应原read_item.py的逻辑

2. 子文件中定义路由与事件逻辑 #

在routers/items.py中，用APIRouter管理路由，并编写事件处理函数：

from fastapi import APIRouter

# 创建路由实例，可统一配置前缀、标签、默认响应等
router = APIRouter(
    prefix="/items",
    tags=["Items"],
    responses={404: {"description": "Item not found"}}
)

# 具体路由实现
@router.get("/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id, "status": "success"}

# 启动事件逻辑
def items_startup():
    # 这里写初始化逻辑，比如连接数据库、加载配置
    print("Items module: 资源初始化完成")

# 关闭事件逻辑
def items_shutdown():
    # 这里写资源释放逻辑，比如关闭数据库连接
    print("Items module: 资源已释放")

3. 主文件组装路由与事件 #

在main.py中创建app实例，注册所有子路由和事件：

from fastapi import FastAPI
from routers.items import router as items_router, items_startup, items_shutdown

app = FastAPI(title="模块化FastAPI服务")

# 注册子路由
app.include_router(items_router)

# 注册事件处理
app.add_event_handler("startup", items_startup)
app.add_event_handler("shutdown", items_shutdown)

进阶：应用工厂模式（复杂项目首选） #

如果项目需要多环境配置或动态依赖注入，推荐用应用工厂函数封装创建逻辑：

# main.py
from fastapi import FastAPI
from routers.items import router as items_router, items_startup, items_shutdown

def create_app():
    app = FastAPI(title="模块化FastAPI服务")
    
    # 注册所有子路由
    app.include_router(items_router)
    
    # 绑定事件处理
    app.add_event_handler("startup", items_startup)
    app.add_event_handler("shutdown", items_shutdown)
    
    return app

app = create_app()

关键注意事项 #

• 禁止子文件直接导入主文件的app实例：这会引发循环导入错误，是FastAPI模块化开发的禁忌。
• APIRouter支持全局配置：可为一组路由设置共同的前缀、权限依赖、标签，大幅提升代码复用性。
• 事件函数支持依赖注入：若事件逻辑需要数据库连接等资源，可通过FastAPI的依赖系统获取，或在应用工厂中提前初始化后传入。

内容的提问来源于stack exchange，提问作者dev