Что такое async def endpoint? Когда использовать вместо def?

Что такое async endpoint

Endpoint, объявленный через async def, — это coroutine function Python. Она может приостанавливаться на операции await, пока ожидает сеть, файловую систему или асинхронную базу данных, не блокируя event loop на это время.

from fastapi import FastAPI

app = FastAPI()


@app.get('/weather')
async def get_weather():
    data = await weather_client.get_current_weather()
    return data

Когда использовать async def

Нужно выбирать async def, если используемая библиотека предоставляет асинхронный API, который вызывается через await: например, async HTTP-клиент, async database driver или асинхронное чтение файлов. Это особенно полезно для I/O-bound задач с большим числом одновременных ожиданий.

Когда использовать обычный def

Если библиотека синхронная и выполняет блокирующий вызов, например обычный синхронный SQLAlchemy Session или синхронный HTTP-клиент, endpoint лучше объявить через def. FastAPI выполнит обычную path operation function в threadpool, чтобы не блокировать основной event loop.

@app.get('/articles/{article_id}')
def get_article(article_id: int):
    article = sync_repository.get(article_id)
    return article

Чего избегать

Не стоит вызывать блокирующий синхронный код напрямую внутри async def: это остановит event loop и ухудшит обработку параллельных запросов. CPU-bound задачи, например обработку больших изображений или сложные вычисления, также лучше выносить в отдельные процессы или очередь задач, например Celery.

Можно ли смешивать

В одном FastAPI-приложении можно использовать и def, и async def. Выбор делают отдельно для каждого endpoint и dependency в зависимости от используемых библиотек и характера операций.

Как ответить на собеседовании

Я использую async def, когда работаю с библиотеками, которые нужно вызывать через await, например async HTTP-клиентом или async драйвером базы. Для синхронных блокирующих библиотек выбираю обычный def; FastAPI выполнит его в threadpool. Не смешиваю блокирующий код с async def без необходимости.