fastapi的`lifespan`事件管理机制是处理应用启动后一次性任务的关键。通过`asynccontextmanager`装饰器，开发者可以在服务器启动前执行初始化逻辑（如数据加载），并在`yield`之后进入服务运行阶段，确保任务不阻塞主应用，从而实现高效的资源管理和应用生命周期控制。
在开发FastAPI应用时，我们经常会遇到这样的需求：需要在应用启动后，但开始处理用户请求之前，执行一些一次性的初始化任务，例如加载配置文件、连接数据库、预热缓存或生成初始数据。直接在if __name__ == "__main__":块中调用这些函数可能会导致它们在Uvicorn服务器启动之前执行，或者在服务器启动之后却无法被调用。FastAPI提供了lifespan事件管理器来优雅地解决这个问题。
理解问题背景
考虑以下场景：一个FastAPI应用需要在一个全局字典DATA中加载一些初始数据，而这个数据生成过程可能需要一定时间。
import time
import uvicorn
from fastapi import FastAPI
DATA = {"value": ""}
app = FastAPI()
@app.get("/")
def get_root():
return DATA
def create_data():
"""模拟耗时的数据初始化操作"""
time.sleep(2)
DATA["value"] = "Hello World!"
if __name__ == "__main__":
# create_data() # 如果在这里调用，会在服务器启动前阻塞主进程
uvicorn.run(app)
# create_data() # 如果在这里调用，服务器启动后，此行代码不会被执行上述代码中，如果create_data()在uvicorn.run(app)之前调用，它会阻塞应用的启动，直到数据生成完毕，用户才能访问API。如果放在uvicorn.run(app)之后，则永远不会被调用，因为uvicorn.run(app)会一直运行直到服务器关闭。我们需要一种机制，让create_data()在服务器准备好接受请求时运行，且只运行一次，而不阻塞服务器的启动流程。
使用 lifespan 管理应用生命周期事件
FastAPI的lifespan事件是解决此类问题的官方推荐方式。它允许我们定义在应用启动和关闭时执行的异步代码块。lifespan通过Python的contextlib.asynccontextmanager装饰器实现，它定义了一个异步上下文管理器。
核心概念
- asynccontextmanager: 这是一个装饰器，用于将一个异步生成器函数转换为一个异步上下文管理器。
-
lifespan 函数: 被@asynccontextmanager装饰的异步生成器函数。
- 在yield语句之前的代码会在应用启动时执行。
- 在yield语句之后的代码会在应用关闭时执行。
- yield语句本身标志着应用已经启动并开始接受请求。
示例代码
下面是使用lifespan来解决上述数据初始化问题的完整示例：
import time
import uvicorn
from fastapi import FastAPI
from contextlib import asynccontextmanager # 导入 asynccontextmanager
# 定义一个全局变量用于存储数据
DATA = {"value": ""}
def create_data():
"""
模拟耗时的数据初始化操作。
这个函数将在应用启动时被调用一次。
"""
print("正在执行数据初始化任务...")
time.sleep(2) # 模拟耗时操作，例如从数据库加载数据或进行复杂计算
DATA["value"] = "Hello World from Lifespan!"
print("数据初始化完成！")
@asynccontextmanager
async def lifespan(app: FastAPI):
"""
FastAPI 应用的生命周期管理器。
在应用启动时执行初始化任务，在应用关闭时执行清理任务。
"""
# ====== 应用启动阶段 ======
# 在这里执行所有应用启动时需要的一次性任务
create_data() # 调用数据初始化函数
print("FastAPI 应用已启动，准备接受请求。")
yield # 应用在此处开始接受 HTTP 请求
# ====== 应用关闭阶段 ======
# 在这里执行所有应用关闭时需要进行的清理任务 (可选)
print("FastAPI 应用正在关闭，执行清理操作...")
# 例如：关闭数据库连接、释放资源等
print("清理完成。")
# 创建 FastAPI 应用实例，并传入 lifespan 函数
app = FastAPI(lifespan=lifespan)
@app.get("/")
def get_root():
"""
根路径接口，返回 DATA 中存储的值。
此接口将在 create_data() 执行完毕后才能被访问到。
"""
return DATA
if __name__ == "__main__":
# 使用 uvicorn 运行 FastAPI 应用
# host 和 port 参数可以根据需要调整
uvicorn.run(app, host="0.0.0.0", port=8000)代码解析
- from contextlib import asynccontextmanager: 导入asynccontextmanager装饰器。
- DATA = {"value": ""}: 定义一个全局字典DATA，用于存储初始化后的数据。
- create_data() 函数: 这是一个普通的同步函数，模拟了耗时的数据生成过程。它会更新DATA字典。
-
@asynccontextmanager async def lifespan(app: FastAPI)::
- @asynccontextmanager将lifespan函数转换为一个异步上下文管理器。
- async def表明这是一个异步函数。
- app: FastAPI参数允许你在lifespan函数中访问FastAPI应用实例，这在需要注册事件处理器或访问应用状态时非常有用。
- create_data(): 这行代码位于yield之前，因此它会在FastAPI服务器完全启动并准备好处理请求之前被执行。由于它是一个同步函数，它会阻塞lifespan函数的执行，直到它完成。这意味着服务器不会开始处理请求，直到create_data()执行完毕。
- yield: 当lifespan函数执行到yield时，FastAPI服务器会认为应用已经启动成功，并开始监听和处理传入的HTTP请求。
- print("FastAPI 应用正在关闭...") 等: 位于yield之后的代码会在FastAPI应用关闭时（例如，当Uvicorn进程被终止时）被执行。这非常适合进行资源清理工作，如关闭数据库连接池、释放文件句柄等。
- app = FastAPI(lifespan=lifespan): 在创建FastAPI应用实例时，通过lifespan参数将我们定义的lifespan函数注册到应用中。
注意事项与最佳实践
- 阻塞操作: 如果lifespan的启动阶段包含耗时的同步操作（如time.sleep()或长时间的数据库查询），这些操作会阻塞整个应用的启动过程，直到它们完成。对于非常耗时的同步任务，可能需要考虑将其异步化，或在单独的线程/进程中执行，以避免长时间阻塞。
- 异步操作: lifespan函数本身是异步的，因此在其中可以直接调用await等待异步任务完成，而不会阻塞事件循环。
- 错误处理: 在lifespan函数中发生的异常会阻止应用启动。确保你的初始化逻辑是健壮的，并包含适当的错误处理。
- 资源清理: lifespan的关闭阶段是进行资源清理的理想场所。确保你在启动时分配的所有资源都能在关闭时被正确释放，以避免资源泄露。
- 全局状态管理: lifespan非常适合初始化全局或应用级别的状态。例如，你可以将数据库连接池、缓存客户端等对象存储在app.state中，并在yield之后进行清理。
通过lifespan机制，FastAPI提供了一种强大且优雅的方式来管理应用的生命周期事件，确保了初始化任务的正确执行，并为应用的健壮性提供了基础。
