FastAPI lifespan: запуск и остановка приложения

Категория: Backend · Язык: Python · Обновлено:

lifespan — асинхронный контекстный менеджер, который FastAPI выполняет при старте и остановке приложения. Код до yield открывает ресурсы, код после — закрывает их. Это современная замена устаревшим @app.on_event("startup") и shutdown; ресурсы удобно хранить в app.state.

Открыть и закрыть ресурсы

Python
from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.ready = True
    print("startup")
    yield
    app.state.ready = False
    print("shutdown")

app = FastAPI(lifespan=lifespan)

@app.get("/health")
async def health():
    return {"ready": app.state.ready}

FastAPI запускает lifespan до приёма запросов и завершает после остановки сервера. Если код до yield выбросит исключение, приложение не стартует — это лучше, чем работать с неинициализированной базой. В finally или после yield закрывайте пулы, HTTP-клиенты и фоновые задачи.

TestClient выполняет lifespan только внутри контекстного менеджера:

Python
from fastapi.testclient import TestClient

with TestClient(app) as client:
    print(client.get("/health").json()["ready"])  # True

Без with TestClient может не запустить startup/shutdown, и тест будет проверять нереалистичное состояние. В production каждый worker (uvicorn/gunicorn) выполняет свой lifespan, поэтому ресурсы не должны быть глобальными для всех процессов.

Не выполняйте в lifespan долгие миграции и блокирующие операции без таймаута: сервер не начнёт принимать трафик. Для тяжёлых задач используйте отдельный job/init-container. Не храните в app.state соединения, которые нельзя безопасно использовать из нескольких event loop.

on_event помечен deprecated; новый код пишите через lifespan. Для синхронных ресурсов можно открыть их в обычной функции и закрыть в finally, но не блокируйте event loop.

Документация: FastAPI lifespan, Starlette lifespan.