本文详细介绍了如何在 fastapi 应用启动后，但在处理任何请求之前，执行一次性初始化任务。通过利用 fastapi 的 `lifespan` 事件处理器和 `asynccontextmanager`，开发者可以优雅地管理应用程序的生命周期，确保数据加载、数据库连接等关键设置在服务器上线前完成，并能在关闭时进行资源清理，从而构建更健壮、专业的应用。
在构建 FastAPI 应用程序时，经常会遇到需要在服务器启动时执行一次性初始化任务的需求，例如加载配置文件、连接数据库、预热缓存或执行某些数据准备工作。这些任务必须在应用程序开始处理客户端请求之前完成。如果处理不当，可能会导致服务器启动阻塞、数据不一致或资源管理混乱。FastAPI 提供了强大的 lifespan 事件处理器来优雅地管理这些生命周期事件。
FastAPI Lifespan 事件处理器
FastAPI 的 lifespan 事件处理器是管理应用程序启动和关闭过程的推荐机制。它基于 Python 的 contextlib.asynccontextmanager，允许开发者定义在应用启动前执行的逻辑（即在 yield 语句之前），以及在应用关闭时执行的清理逻辑（即在 yield 语句之后）。这种模式确保了初始化任务的顺序性，并且在应用程序生命周期内提供了清晰的资源管理。
实现应用启动时的一次性任务
为了在 FastAPI 应用启动后、接收请求前执行一次性任务，我们需要遵循以下步骤：
- 定义初始化函数：创建需要执行的初始化逻辑，例如加载数据或建立连接。
- 创建 asynccontextmanager：使用 @asynccontextmanager 装饰器定义一个异步上下文管理器函数，该函数将作为 lifespan 处理器。
- 在 yield 前执行任务：将初始化函数调用放置在 lifespan 函数的 yield 语句之前。这将确保在应用程序开始处理请求之前，所有启动逻辑都已完成。
- 将 lifespan 传入 FastAPI 应用：在创建 FastAPI 实例时，通过 lifespan 参数指定我们定义的上下文管理器。
下面是一个具体的示例，演示如何使用 lifespan 在 FastAPI 服务器启动后加载全局数据：
import time
import uvicorn
from fastapi import FastAPI
from contextlib import asynccontextmanager
# 模拟全局数据或资源
DATA = {"value": ""}
# 模拟需要执行的初始化函数，例如加载数据
def create_data():
"""
此函数模拟一个耗时的数据初始化过程。
它会在应用启动时被调用一次。
"""
print(">>> [启动阶段] 正在执行数据初始化...")
time.sleep(2) # 模拟耗时操作，例如从数据库加载数据
DATA["value"] = "Hello World! (Data Loaded by Lifespan)"
print("<<< [启动阶段] 数据初始化完成。")
# 定义应用生命周期管理器
@asynccontextmanager
async def app_lifespan(app: FastAPI):
"""
FastAPI 应用的生命周期管理器。
在 'yield' 之前执行启动逻辑，在 'yield' 之后执行关闭逻辑。
"""
# --- 启动阶段 ---
print(">>> 应用启动中...")
create_data() # 在应用启动并接收请求前执行一次性任务
print("<<< 应用准备就绪，开始接收HTTP请求。")
yield # 应用程序在此点开始处理请求
# --- 关闭阶段 ---
print(">>> 应用关闭中...")
# 可以在此处添加资源清理逻辑，例如关闭数据库连接池、释放文件句柄等
# 例如：close_database_connection()
print("<<< 应用已关闭。")
# 创建FastAPI应用实例，并传入自定义的lifespan管理器
app = FastAPI(lifespan=app_lifespan)
@app.get("/")
def get_root():
"""
一个简单的API端点，返回由启动任务初始化的数据。
"""
return {"message": DATA["value"]}
if __name__ == "__main__":
print("尝试启动 FastAPI 应用...")
uvicorn.run(app, host="0.0.0.0", port=8000)
print("FastAPI 应用已退出。")代码解析与注意事项
- DATA = {"value": ""}：这是一个简单的全局字典，用于模拟在应用启动时需要初始化的数据。
-
create_data() 函数：
- 这个函数包含了具体的初始化逻辑，例如 time.sleep(2) 模拟了一个耗时操作。
- 它是一个同步函数。在 lifespan 的启动阶段（yield 之前）调用同步阻塞函数是可行的，因为 lifespan 本身会等待这些任务完成。这意味着服务器不会开始处理请求，直到 create_data 完成。这正是许多场景下期望的行为。
-
@asynccontextmanager 装饰器：
- 这是 contextlib 模块提供的一个强大工具，用于将异步生成器函数转换为异步上下文管理器。
- 它使得 app_lifespan 函数能够像 with 语句一样管理资源的进入和退出。
-
async def app_lifespan(app: FastAPI):：
- 这是我们自定义的生命周期处理器。FastAPI 会在应用启动时调用它。
- app 参数是当前的 FastAPI 应用实例，可以在生命周期函数中访问它。
-
create_data() 调用位置：
- create_data() 被放在 yield 语句之前。这保证了在 yield 之后的代码（即应用程序开始处理 HTTP 请求）执行之前，数据初始化任务已经完成。
-
yield 关键字：
- yield 是 lifespan 事件处理器的核心。当执行流到达 yield 时，表示应用程序已经完成了所有启动准备，现在可以开始接收和处理 HTTP 请求了。
- yield 之后的部分则用于处理应用程序关闭时的清理工作。当服务器关闭时（例如通过 Ctrl+C 停止 uvicorn），执行流会从 yield 之后继续，执行清理逻辑。
-
app = FastAPI(lifespan=app_lifespan)：
- 在创建 FastAPI 应用实例时，通过 lifespan 参数将我们定义的 app_lifespan 上下文管理器传递给应用。这是激活生命周期事件的关键步骤。
总结
通过 FastAPI 提供的 lifespan 事件处理器，开发者能够以一种结构化且非侵入式的方式，优雅地管理应用程序的启动和关闭过程。这不仅确保了在服务器上线前完成必要的初始化任务，还提供了在应用关闭时进行资源清理的机制，从而显著提升了 FastAPI 应用的健壮性、可维护性和专业性。对于任何需要进行启动时设置或关闭时清理的 FastAPI 项目，lifespan 都是一个不可或缺的工具。
