FastAPI BackgroundTasks: ответить и продолжить работу

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

BackgroundTasks позволяет вернуть ответ клиенту и только потом выполнить лёгкую задачу: отправить письмо, записать аудит, прогреть кеш. Задачи выполняются в том же процессе после отправки ответа, поэтому это не очередь и не замена Celery для тяжёлой работы. При падении процесса задача потеряется.

Поставить задачу после ответа

Python
from fastapi import BackgroundTasks, FastAPI

app = FastAPI()

def send_email(to: str, subject: str) -> None:
    print(f"email to {to}: {subject}")

@app.post("/users/{user_id}/notify")
async def notify(user_id: int, background_tasks: BackgroundTasks):
    background_tasks.add_task(send_email, "user@example.com", f"user {user_id}")
    return {"status": "queued"}

FastAPI внедряет BackgroundTasks в обработчик; add_task принимает функцию и аргументы, но не вызывает её сразу. Ответ уходит клиенту, затем Starlette выполняет задачи. Синхронная функция выполняется в threadpool, асинхронная — в event loop; не блокируйте loop тяжёлым кодом.

Проверить выполнение в тесте

Python
from fastapi import BackgroundTasks, FastAPI
from fastapi.testclient import TestClient

app = FastAPI()
done = []

def record(value: str) -> None:
    done.append(value)

@app.post("/jobs")
async def create_job(background_tasks: BackgroundTasks):
    background_tasks.add_task(record, "ok")
    return {"status": "accepted"}

client = TestClient(app)
response = client.post("/jobs")
print(response.json()["status"])  # accepted
print(done)                       # ['ok']

TestClient дожидается выполнения фоновых задач, поэтому список done уже заполнен. В реальном сервере задача стартует после ответа, и клиент не получает её результат. Если задача должна быть видимой в другом процессе или переживать рестарт, используйте очередь (Celery, RQ, Arq) и отдельного worker'а.

Не передавайте в add_task объекты запроса, соединения с БД и другие ресурсы, которые закрываются после ответа. Передавайте простые значения или ID и открывайте соединение внутри задачи. Для длинных задач настройте таймауты и идемпотентность: повторный запуск не должен дублировать письмо или списание.

BackgroundTasks выполняет задачи по очереди в рамках одного ответа; если задача падает, ошибка логируется, но ответ уже отправлен. Для критичных операций нужна очередь с ретраями и мониторингом.

Документация: Background Tasks, Starlette background.