Жизненный цикл запроса: луковица middleware, резолв зависимостей, lifespan и где всплывают ошибки

Путь внутрь: accept, scope, луковица, роут

uvicorn принимает TCP-соединение, парсит HTTP в ASGI-scope и вызывает внешнее приложение. Дальше запрос идёт по луковице: каждый middleware — это ASGI-приложение, оборачивающее следующее; код на пути внутрь, вызов вглубь, затем код на пути наружу, когда ответ проходит обратно. Порядок поэтому — архитектура, а порядок регистрации в Starlette сбивает с толку: add_middleware оборачивает текущий стек, так что последний добавленный middleware — внешний: он видит запрос первым, а ответ последним:

app.add_middleware(AuthMiddleware)        # добавлен первым  → внутренний
app.add_middleware(RequestIdMiddleware)   # добавлен вторым → ВНЕШНИЙ, бежит первым

# запрос: RequestId → Auth → роутер → хендлер
# ответ:  хендлер → Auth → RequestId

Порядок кодирует политику. Request-id и логирование — наружу, чтобы каждый запрос, включая отклонённые позже, был наблюдаем. Что идёт следующим — auth или rate-limiting — настоящее решение: пер-пользовательскому лимиту нужен уже отработавший auth (он ключуется на идентичности); пер-IP лимит ставят снаружи auth, чтобы неаутентифицированный флуд не жёг CPU на верификации токенов. За луковицей роутер матчит путь и метод, и матчинг передаёт управление самой недооценённой стадии конвейера — резолву зависимостей.

Зависимости: граф на запрос со скоупнутым teardown

FastAPI резолвит граф зависимостей хендлера заново на каждый запрос, с двумя свойствами продакшенного веса. Первое — кэширование: одна и та же зависимость, встречающаяся в графе запроса несколько раз, выполняется один раз, и результат делят все (use_cache=True — дефолт): get_current_user в хендлере, проверке прав и аудит-зависимости — это одна верификация токена, а не три. Второе — yield-зависимости как скоупнутые ресурсы: код до yield выполняется на входе, отданное значение инжектится, код после yield — teardown, который гарантированно выполнится, в том числе когда хендлер бросает исключение:

async def get_conn(request: Request):
    async with request.app.state.pool.acquire() as conn:   # одолжить из lifespan-пула
        async with conn.transaction():
            yield conn                                     # здесь работает хендлер
        # commit/rollback + возврат соединения — на размотке

У тайминга teardown есть зубы: начиная с FastAPI 0.106 teardown yield-зависимостей выполняется после отправки ответа, но до запуска фоновых задач. Фоновая задача, потянувшаяся к сессии БД запроса, найдёт её закрытой — сессии для фоновой работы создаёт сама задача, а не одалживает у зависимости, чей teardown уже отработал.

Lifespan владеет процессными ресурсами

Scope lifespan (жизненный цикл процесса — ASGI-событие, срабатывающее при старте и остановке воркера) из урока 1 — место, где строится всё, что живёт столько же, сколько процесс: пулы соединений, HTTP-клиенты, веса моделей, кэши. Они создаются один раз на воркер при старте, расшариваются через app.state и чисто закрываются при остановке:

@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.pool = await asyncpg.create_pool(DSN, min_size=5, max_size=10)
    yield                                   # здесь приложение обслуживает запросы
    await app.state.pool.close()

app = FastAPI(lifespan=lifespan)

Инцидент из Хука — каноническая инверсия этого правила: пул на запрос вместо пула на процесс. Арифметику стоит держать под рукой: пул стоит рукопожатия соединения (~сотни мс на TLS + аутентификацию) и держит сокеты открытыми; у Postgres по умолчанию max_connections = 100. Один пул на 10 на воркер × 4 воркера × 2 пода = 80 соединений — осознанно и стабильно. Один пул на запрос при 50 rps = потолок пробит за секунды, и отказ приходит в виде чужих 500-х.

После ответа: фоновые задачи, стриминг и где всплывают ошибки

Прежде чем тянуться к BackgroundTasks, спроси себя: должна ли эта задача пережить деплой? Нужны ли ей ретраи при сбое? Если хоть одно «да» — ей здесь не место. BackgroundTasks выполняет функции после отправки ответа — на том же воркере. В этом и фича, и ловушка: клиент разблокирован, а воркер — нет. Генератор отчёта на 60 секунд, повешенный фоновой задачей, занимает воркер после каждого ответа; при умеренном трафике цикл (или тредпул — для синхронных задач) навсегда занят не-запросной работой, а задачи умирают вместе с процессом на деплое — они в памяти, без ретраев, без наблюдаемости. Честное правило: фоновые задачи — для субсекундного fire-and-forget (поставить письмо в очередь, тронуть кэш); всё тяжелее уходит в настоящую очередь с ретраями и собственными воркерами. Для больших payload-ов StreamingResponse с асинхронным генератором отправляет чанки по мере производства — CSV-экспорт на 2 ГБ стримится в константной памяти вместо материализации в RAM.

Ошибки всплывают на фиксированных слоях, и знать, какой слой отвечает, — большая часть отладки. Отказ валидации происходит при резолве аргументов и зависимостей — хендлер не запускается, клиент получает 422 с адресами полей. HTTPException, брошенный в хендлере или зависимости, ловится exception-слоем фреймворка и рендерится своим статус-кодом, а teardown yield-зависимостей всё равно выполняется. Необработанное исключение распространяется наружу сквозь луковицу — каждый middleware на пути его видит (ваш логирующий middleware может его записать), — пока внешний слой server-error не ответит 500. Ответ в этот момент уже потерян; порядок ваших middleware решает лишь, кто успеет осмотреть тело.