0Pricing
FastAPI Backend Development Bootcamp · Урок

Лёгкая передача работы в фон с BackgroundTasks

Используйте встроенный в FastAPI BackgroundTasks для фоновых побочных эффектов без ожидания результата и блокировки ответа.

«Лёгкая передача работы в фон с BackgroundTasks» — бесплатный урок FastAPI Backend Development Bootcamp на CoddyKit. Это урок 1 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения FastAPI Backend Development Bootcamp, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс FastAPI Backend Development Bootcamp содержит 4 уроков всего.

Части этого урока еще не переведены и отображаются на английском.

Why Offload Work?

When a client sends a request, they wait for the response. If your endpoint also sends a welcome email, writes an audit log, or warms a cache, the user is stuck waiting for work they don't care about.

Fire-and-forget side effects are tasks that should run after the response is sent, without blocking it:

  • Sending notification emails
  • Writing analytics or audit logs
  • Invalidating or warming caches
  • Cleaning up temporary files

FastAPI ships a built-in tool for exactly this: BackgroundTasks.

Declaring BackgroundTasks

To use it, add a parameter typed as BackgroundTasks to your path operation function. FastAPI sees the type annotation and injects an instance for you, just like any other dependency.

You then register work with .add_task(func, *args, **kwargs). The function is not called immediately, it is queued to run once the response has been returned.

from fastapi import BackgroundTasks, FastAPI

app = FastAPI()


def write_log(message: str) -> None:
    with open("log.txt", mode="a") as f:
        f.write(message + "\n")


@app.post("/signup")
async def signup(email: str, tasks: BackgroundTasks):
    tasks.add_task(write_log, f"signup: {email}")
    return {"status": "accepted"}

The Execution Order

The critical detail: background tasks run after the response is sent to the client, but still within the same server process.

  • The endpoint returns its dict or Response.
  • FastAPI flushes the response over the network.
  • Only then does it execute each queued task, in the order they were added.

So the user gets an instant 202-style reply while the email or log happens behind the scenes.

Passing Arguments to a Task

Arguments you pass to add_task are stored and forwarded when the task finally runs. Positional and keyword arguments both work.

This pattern keeps the side-effect logic in a plain function that is easy to unit-test in isolation, completely independent of FastAPI.

from fastapi import BackgroundTasks, FastAPI

app = FastAPI()


def send_email(to: str, subject: str, body: str) -> None:
    # imagine an SMTP client here
    print(f"Sending to {to}: {subject}")


@app.post("/orders")
async def create_order(email: str, tasks: BackgroundTasks):
    order_id = 1234
    tasks.add_task(
        send_email,
        to=email,
        subject="Order confirmed",
        body=f"Your order {order_id} is on the way!",
    )
    return {"order_id": order_id}

Sync vs Async Task Functions

A task function can be either a normal def or an async def.

  • An async task is awaited directly on the event loop.
  • A regular def task is run in a thread pool so it doesn't block the loop.

Rule of thumb: if your side effect does blocking I/O (file writes, a synchronous DB driver), a plain def is fine, FastAPI offloads it to a thread. Use async def only when you genuinely await async I/O.

async def notify_async(user_id: int) -> None:
    # awaits an async HTTP client, for example
    await some_async_push(user_id)


def notify_sync(user_id: int) -> None:
    # blocking call, run in a threadpool by FastAPI
    requests_post(user_id)

Adding Multiple Tasks

You can call add_task as many times as you like. Tasks run sequentially in the exact order added, each completing before the next begins.

Because they run one after another, a slow task delays the ones queued behind it, but never the HTTP response itself.

from fastapi import BackgroundTasks, FastAPI

app = FastAPI()


@app.post("/publish")
async def publish(post_id: int, tasks: BackgroundTasks):
    tasks.add_task(reindex_search, post_id)
    tasks.add_task(invalidate_cache, post_id)
    tasks.add_task(notify_followers, post_id)
    return {"published": post_id}

Using BackgroundTasks in Dependencies

A powerful trick: a dependency can also declare a BackgroundTasks parameter and queue tasks. FastAPI merges everything into one shared task set for that request.

This lets cross-cutting concerns, like audit logging, live in a reusable dependency instead of being copy-pasted into every endpoint.

from fastapi import BackgroundTasks, Depends, FastAPI

app = FastAPI()


def audit(action: str, tasks: BackgroundTasks):
    tasks.add_task(write_audit_row, action)
    return action


@app.delete("/items/{item_id}")
async def delete_item(item_id: int, action=Depends(audit)):
    return {"deleted": item_id}

A Plain-Python Task Queue Mental Model

Under the hood, BackgroundTasks is little more than a list of callables that get run after the response. You can model the idea in pure Python to build intuition.

The snippet below is standalone, no FastAPI needed, showing the add-then-run-later pattern.

class TaskList:
    def __init__(self):
        self.tasks = []

    def add_task(self, func, *args, **kwargs):
        self.tasks.append((func, args, kwargs))

    def run_all(self):
        for func, args, kwargs in self.tasks:
            func(*args, **kwargs)


def log(msg):
    print("LOG:", msg)


q = TaskList()
q.add_task(log, "user signed up")
q.add_task(log, "email queued")
print("response sent")
q.run_all()

Error Handling Inside Tasks

Because a task runs after the response, you can no longer turn its failure into an HTTP error, the client already got a 200.

An unhandled exception in a background task is logged by the server but is invisible to the client. Always wrap risky work in try/except and decide on retries or a dead-letter strategy yourself.

def send_receipt(order_id: int) -> None:
    try:
        deliver_email(order_id)
    except Exception as exc:
        # the client already has its 200, so log and recover here
        logger.exception("receipt failed for %s: %s", order_id, exc)
        schedule_retry(order_id)

The Big Limitation: Same Process

BackgroundTasks runs in the same worker process as your app. That brings real constraints:

  • Heavy CPU work still consumes that worker's resources.
  • If the process crashes or is redeployed, queued tasks are lost, there is no persistence.
  • Tasks don't survive across multiple machines or scale horizontally.

It is perfect for lightweight, best-effort side effects, but not for reliable, long-running, or distributed jobs.

When to Reach for Celery Instead

Choose BackgroundTasks when the work is short, non-critical, and OK to lose on a crash, sending an email, bumping a counter, deleting a temp file.

Reach for Celery or another distributed queue (RQ, Dramatiq, Arq) when you need:

  • Durability, jobs survive restarts via a broker like Redis/RabbitMQ.
  • Retries, scheduling, and rate limiting.
  • Horizontal scaling across dedicated worker machines.
  • Heavy CPU jobs that would otherwise starve your web workers.

Quick Check

Test your understanding of when BackgroundTasks is the right tool.

Recap

Key takeaways:

  • Add a BackgroundTasks parameter and call add_task(func, *args, **kwargs) to defer side effects.
  • Tasks run after the response, sequentially, in the same worker process.
  • Sync def tasks run in a thread pool; async def tasks run on the event loop.
  • Dependencies can queue tasks too, great for cross-cutting concerns like auditing.
  • No persistence: failures are invisible to the client and tasks die with the process.
  • Use it for lightweight, best-effort work; choose Celery for durable, retryable, distributed, or CPU-heavy jobs.

Часто задаваемые вопросы

Урок «Лёгкая передача работы в фон с BackgroundTasks» бесплатный?

Да — полный текст урока «Лёгкая передача работы в фон с BackgroundTasks» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс FastAPI Backend Development Bootcamp, подпишись на CoddyKit PRO. Курс FastAPI Backend Development Bootcamp содержит 4 уроков всего.

Чему я научусь в уроке «Лёгкая передача работы в фон с BackgroundTasks»?

Используйте встроенный в FastAPI BackgroundTasks для фоновых побочных эффектов без ожидания результата и блокировки ответа. Ты практикуешь FastAPI Backend Development Bootcamp с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать FastAPI Backend Development Bootcamp?

Предыдущий опыт не требуется. FastAPI Backend Development Bootcamp на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 1 из 4.

Сколько времени занимает урок «Лёгкая передача работы в фон с BackgroundTasks»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке FastAPI Backend Development Bootcamp?

Да. Каждый урок FastAPI Backend Development Bootcamp включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

  1. Лёгкая передача работы в фон с BackgroundTasks
  2. Подключение рабочих процессов Celery к приложению FastAPI
  3. Повторные попытки, идемпотентность и обработка недоставленных сообщений
  4. Запланированные и периодические задания с Celery Beat
← Назад к FastAPI Backend Development Bootcamp