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