本文详细介绍了如何在fastapi应用启动后，利用其内置的`lifespan`事件管理机制执行一次性初始化函数。通过`asynccontextmanager`装饰器定义生命周期函数，并将其传递给`fastapi`实例，可以确保特定任务（如数据加载、数据库连接初始化）在服务器开始处理请求前完成，从而实现对应用启动流程的精确控制。
在开发Web应用程序时，我们经常需要在服务器启动后、开始处理用户请求之前执行一些初始化任务。这些任务可能包括加载配置、初始化数据库连接、预加载数据到内存或启动后台服务等。对于FastAPI应用，直接在if __name__ == "__main__":块中调用函数可能无法满足“服务器启动后”的要求，因为这些函数会在Uvicorn启动之前执行，或者在Uvicorn启动后无法被调用。FastAPI提供了一个优雅的解决方案：lifespan事件管理。
使用 lifespan 管理应用生命周期事件
FastAPI的lifespan机制允许开发者定义在应用启动和关闭时需要执行的异步任务。它通过Python的contextlib.asynccontextmanager装饰器实现，提供了一个清晰的上下文管理模式。
lifespan 的工作原理
lifespan 函数是一个异步上下文管理器，其核心在于yield关键字。在yield之前执行的代码会在应用启动时运行，而yield之后（或yield块退出时）执行的代码则会在应用关闭时运行。这使得我们能够精确地控制初始化和清理操作的执行时机。
实现启动时一次性函数
假设我们有一个名为 create_data 的函数，需要在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 from FastAPI!"
print("数据初始化完成。")
# 定义应用生命周期管理器
@asynccontextmanager
async def lifespan(app: FastAPI):
"""
FastAPI应用的生命周期管理函数。
在yield之前执行启动任务，在yield之后（或退出时）执行关闭任务。
"""
create_data() # 在应用启动时调用一次性初始化函数
print("FastAPI应用即将启动并接受请求...")
yield # 应用在此处开始接受请求
# yield之后的代码将在应用关闭时执行
print("FastAPI应用正在关闭...")
# 例如，可以在这里清理资源
DATA["value"] = "" # 清理数据
print("资源已清理。")
# 创建FastAPI应用实例，并注册lifespan事件
app = FastAPI(lifespan=lifespan)
@app.get("/")
def get_root():
"""
根路径接口，返回初始化后的数据。
"""
return DATA
if __name__ == "__main__":
print("启动Uvicorn服务器...")
uvicorn.run(app, host="0.0.0.0", port=8000)
print("Uvicorn服务器已停止。")
代码解析
- DATA 变量：一个简单的字典，用于存储需要被 create_data 函数初始化的数据。
- create_data() 函数：这是一个同步函数，模拟了数据加载或任何其他初始化任务。它会暂停2秒，然后更新 DATA 字典。
- @asynccontextmanager 装饰器：这是定义 lifespan 函数的关键。它将一个异步生成器函数转换为一个异步上下文管理器。
- async def lifespan(app: FastAPI):：这是我们的生命周期函数。它接受一个 FastAPI 应用实例作为参数（尽管在这个例子中没有直接使用，但在更复杂的场景中可能需要）。
- create_data() 调用：在 yield 语句之前，我们调用了 create_data() 函数。这意味着在FastAPI服务器开始监听传入请求之前，create_data() 会被完整执行。
- yield 关键字：这是 lifespan 函数的核心。当执行流到达 yield 时，FastAPI应用会正式启动并开始处理HTTP请求。
- yield 之后的代码：在应用关闭时（例如，当Uvicorn进程被终止时），执行流会从 yield 之后继续，从而允许我们执行清理任务。
- app = FastAPI(lifespan=lifespan)：在创建 FastAPI 应用实例时，通过 lifespan 参数将我们定义的 lifespan 函数注册到应用中。
运行示例
当你运行上述代码时，你会观察到以下输出顺序：
启动Uvicorn服务器...
开始执行数据初始化...
数据初始化完成。
FastAPI应用即将启动并接受请求...
INFO: Started reloader process [xxxxx] using WatchFiles
INFO: Started server process [xxxxx]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
# 此时服务器正在运行，你可以通过浏览器或curl访问 http://0.0.0.0:8000
# 访问后会返回 {"value": "Hello World from FastAPI!"}
# 当你按下 CTRL+C 停止服务器时：
INFO: Shutting down
INFO: Waiting for application shutdown.
FastAPI应用正在关闭...
资源已清理。
INFO: Application shutdown complete.
INFO: Finished server process [xxxxx]
INFO: Stopping reloader process [xxxxx]
Uvicorn服务器已停止。这清楚地表明 create_data() 在服务器开始接受请求之前完成执行，并且关闭逻辑在服务器停止后被触发。
注意事项与最佳实践
- 异步操作：如果你的初始化任务本身是异步的（例如，等待数据库连接、调用外部API），那么 create_data 函数也应该被定义为 async def，并在 lifespan 中使用 await create_data() 调用。
- 错误处理：在 lifespan 函数内部的启动代码中加入适当的错误处理机制。如果启动任务失败，应抛出异常，阻止应用正常启动。
- 资源清理：充分利用 yield 之后的代码块进行资源清理，如关闭数据库连接池、文件句柄、释放锁等，确保应用优雅关闭。
- 超时设置：如果启动任务耗时过长，Uvicorn可能会因为启动超时而终止。对于特别耗时的任务，考虑将其拆分为后台任务或在应用外部预先完成。
- 全局状态管理：lifespan 是初始化全局状态的理想场所，但请注意管理共享状态的并发访问问题，尤其是在生产环境中。
总结
FastAPI的 lifespan 事件管理机制提供了一种强大且优雅的方式来处理应用的启动和关闭任务。通过利用 asynccontextmanager 和 yield 关键字，开发者可以精确地控制初始化函数的执行时机，确保应用在处理请求前处于正确的状态，并在关闭时进行必要的资源清理，从而构建出更加健壮和专业的FastAPI应用。
