【无标题】

原创

于 2026-05-14 16:42:59 发布 · 269 阅读

标签

#fastapi

FastAPI 生命周期进阶！@app.on_event 与 lifespan 全方位对比（含迁移指南）

✅ 专栏：FastAPI 实战教程

✅ 适用场景：后端开发、FastAPI 项目迭代、老旧项目迁移

✅ 核心亮点：零基础看懂、代码可直接复用、生产级最佳实践

前言

在 FastAPI 后端项目开发中，服务生命周期管理是保障项目稳定运行的核心基础能力，几乎是所有企业级项目的必做配置。

正常项目上线部署，必须依托生命周期完成两大核心操作：

服务启动阶段：初始化数据库连接、加载全局配置、预热AI模型、创建数据库/Redis连接池
服务关闭阶段：释放各类资源、关闭连接池、缓存落盘、销毁全局实例，避免内存泄漏

FastAPI 框架迭代至今，共存两套生命周期实现方案：

老旧废弃方案：@app.on_event(startup) / @app\.on\_event\(\&\#34;shutdown\&\#34;\)
新版官方推荐方案：lifespan 上下文生命周期

重点提醒：on\_event 已被 FastAPI 官方标记废弃，新版框架逐步移除该API，lifespan 是目前生产环境唯一合规、稳定的写法。

本文将从零拆解两套方案的差异、实战演示完整代码、梳理避坑要点，并提供老旧项目一键迁移方案，所有代码可直接复制用于企业项目开发。

一、版本迭代说明（必看！避免版本兼容报错）

FastAPI 0.95.0 之前版本：主流使用 on_event 实现生命周期，无 lifespan 方案
FastAPI 0.95.0+ 新版本：正式推出 lifespan，同时标记 on\_event 为废弃 API
FastAPI 后续迭代版本：将彻底删除 on\_event 相关接口，不再兼容旧写法

总结建议：所有新建 FastAPI 项目统一使用 lifespan；存量老旧项目建议尽早完成迁移，避免框架升级后项目报错瘫痪。

二、两套生命周期方案完整实战代码

1、传统方案：@app.on_event（废弃｜不推荐使用）

方案特点：启动、关闭逻辑代码分散，全局变量共享数据，代码耦合度高、维护性差

from fastapi import FastAPI
import uvicorn

app = FastAPI()

# 依赖全局变量共享状态（存在变量污染、线程安全问题）
db_conn = None

@app.on_event("startup")
async def startup():
    """服务启动、接收用户请求前自动执行"""
    global db_conn
    print("✅ 服务启动：初始化数据库、加载全局配置")
    db_conn = "数据库连接成功"

@app.on_event("shutdown")
async def shutdown():
    """服务停止、进程退出前自动执行"""
    print("❌ 服务关闭：释放资源、关闭数据库连接")

@app.get("/")
def index():
    return {
   
   "msg": "on_event 旧版废弃写法", "db_status": db_conn}