FastAPI 应用启动后执行一次性任务：Lifespan 事件管理详解-Python教程-PHP中文网

FastAPI 应用启动后执行一次性任务：Lifespan 事件管理详解

碧海醫心

发布： 2025-10-29 15:07:00

原创

845人浏览过

FastAPI 应用启动后执行一次性任务：Lifespan 事件管理详解

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装饰器实现，它定义了一个异步上下文管理器。

AppMall应用商店

AI应用商店，提供即时交付、按需付费的人工智能应用服务

查看详情

核心概念

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之后进行清理。