К содержимому
Войти

Python Road Map

⚡ FastAPI: маршруты, зависимости и lifespan

FastAPI строит почти всё на одной идее: что нужно обработчику, он объявляет в сигнатуре, а фреймворк это достаёт, проверяет и подставляет. Тело запроса, параметры пути, сессия базы и текущий пользователь приходят одним механизмом, и из тех же аннотаций собирается OpenAPI-схема. На собеседовании спрашивают именно эту механику: как устроен Depends, когда выполняется код после yield, зачем lifespan и откуда берётся 422. Как запрос доходит до приложения через uvicorn, разобрано на странице про WSGI и ASGI, здесь начинаем с момента, когда он попал в FastAPI

🧠 Как это устроено

Маршрут и модели запроса и ответа

Каждый параметр обработчика FastAPI относит к одному из источников:

  • есть в шаблоне пути (/users/{user_id}) — параметр пути
  • простой тип (int, str, bool) вне пути — query-параметр
  • Pydantic-модель — тело запроса в JSON
  • Depends(...) — зависимость, о ней ниже

Входные данные проходят валидацию Pydantic до вызова обработчика. С FastAPI 0.128.0 (вышел 27 декабря 2025) поддерживается только Pydantic v2: модели из pydantic.v1 больше не принимаются. Как писать сами модели, разобрано на странице про Pydantic v2

Ответ описывают аннотацией возвращаемого типа (-> UserOut) или параметром response_model=UserOut, при обоих побеждает response_model. Модель ответа проверяет данные, попадает в документацию и отбрасывает поля, которых в ней нет. Поэтому модели на вход и на выход разные: UserIn с паролем, UserOut без него. Обработчик может вернуть словарь или ORM-объект целиком, и password не уйдёт клиенту. Если же данные не прошли модель ответа, клиент получит 500, а не 422: виноват сервер, в логе будет ResponseValidationError

Depends и дерево зависимостей

Зависимость — обычная функция или класс. FastAPI читает её сигнатуру так же, как сигнатуру обработчика, поэтому у зависимости бывают свои параметры запроса и свои зависимости. Получается дерево, и перед запросом FastAPI обходит его от листьев к обработчику

Документация рекомендует аннотированный стиль:

Session = Annotated[AsyncSession, Depends(get_session)]

@app.get("/orders")
async def list_orders(session: Session, user: CurrentUser): ...

Тип и способ его получить живут в одном псевдониме, который переиспользуют по всему проекту. Старый стиль session: AsyncSession = Depends(get_session) работает, но прячет зависимость в значение по умолчанию

За один запрос зависимость вызывается один раз. Если get_session нужна и обработчику, и get_current_user, FastAPI вызовет её однажды и отдаст обоим одно значение, поэтому оба работают в одной транзакции. Кэш отключают через Depends(get_value, use_cache=False), это нужно редко. Между запросами кэша нет

Зависимость без значения вешают списком: dependencies=[Depends(verify_token)] у маршрута, APIRouter или всего приложения. Так делают проверки, результат которых обработчику не нужен

Зависимости с yield

Зависимость с yield — контекстный менеджер в форме генератора. До yield она готовит ресурс, yield отдаёт его обработчику, после yield убирает за собой:

async def get_session(request: Request):
    async with request.app.state.sessionmaker() as session:
        yield session

Когда выполняется код после yield, менялось несколько раз:

Версия FastAPIКогда выполняется код после yield
до 0.106.0после отправки ответа
0.106.0–0.117после обработчика, но до отправки ответа
0.118.0 и новеепо умолчанию снова после отправки ответа
0.121.0 и новееDepends(dep, scope="function") закрывает ресурс до отправки ответа

В 0.118.0 поведение вернули из-за StreamingResponse: к моменту отдачи тела сессию уже закрывали. Сейчас по умолчанию scope="request", и ресурс живёт, пока ответ не ушёл целиком. Исключение после yield ответ уже не изменит. Если там commit и он упал, клиент получит 200, хотя данных в базе нет, а с scope="function" та же ошибка вернёт 500. Поэтому commit делают явно в сервисе или ставят такой зависимости scope="function"

С 0.110.0 действует ещё одно правило: если зависимость поймала исключение в except и не пробросила, FastAPI о нём не узнает. Клиент получит 500, а в логе сервера пусто. В except пишут raise или поднимают HTTPException

Lifespan и app.state

Пул соединений, HTTP-клиент, ML-модель создают один раз на процесс. Для этого есть lifespan: асинхронный контекстный менеджер, который передают в FastAPI(lifespan=...). Код до yield выполняется до первого запроса, после yield — при остановке сервера

Раньше то же делали через @app.on_event("startup") и "shutdown". Сейчас декоратор пишет DeprecationWarning, а в Starlette 1.0 его удалили совсем, FastAPI держит только совместимость. Lifespan удобнее по трём причинам. Открытие и закрытие ресурса стоят в одной функции, и переменная со старта видна при остановке без глобалов. Если старт упал на середине, async with внутри lifespan закроет уже открытое. И это стандартный протокол ASGI, его одинаково понимают сервер и тестовый клиент

Смешивать нельзя: если передан lifespan, обработчики on_event не вызываются вовсе, и запуск это подтверждает. Lifespan выполняется только у главного приложения, у подприложений из mount — нет

Пул из lifespan кладут в app.state.pool, а в зависимости читают request.app.state.pool. Вариант аккуратнее — lifespan state: yield {"pool": pool}, и Starlette передаёт словарь в request.state каждого запроса

Middleware или зависимость

Middleware оборачивает всё приложение: видит каждый запрос, включая 404 на несуществующий путь, и готовый ответ. Зависимость привязана к маршруту: её параметры валидируются и попадают в OpenAPI, и она возвращает значение в обработчик

ЗадачаЧто выбратьПочему
Логирование, request id, метрикиmiddlewareнужно на каждый запрос, включая 404 и ошибки
CORS, сжатие, заголовки безопасностиmiddlewareкасается всех ответов одинаково
Авторизациязависимостьобработчику нужен пользователь, права у маршрутов разные, схема безопасности видна в /docs
Сессия и транзакция БДзависимостьнужна не всем маршрутам и должна попасть в обработчик

HTTPException, поднятый в @app.middleware("http"), до обработчиков исключений не доходит: middleware стоит снаружи слоя, который их обрабатывает, и клиент получает 500. Из middleware ответ возвращают явно, через JSONResponse

Ошибки: HTTPException, 422 и свои обработчики

raise HTTPException(status_code=404, detail="user not found") в обработчике или зависимости даёт ответ {"detail": "user not found"}

422 означает, что запрос не прошёл валидацию: в пути abc вместо int, в JSON нет обязательного поля. Внутри поднимается RequestValidationError, и стандартный обработчик отдаёт список ошибок с полями type, loc, msg, input. По loc видно место: ["path", "user_id"] или ["body", "email"]. Формат меняют своим обработчиком:

@app.exception_handler(RequestValidationError)
async def on_validation_error(request: Request, exc: RequestValidationError):
    fields = [".".join(map(str, e["loc"])) for e in exc.errors()]
    return JSONResponse(status_code=400, content={"error": "bad_request", "fields": fields})

Запрос /n/x?q=y с двумя ошибками вернул на нём 400 {"error": "bad_request", "fields": ["path.n", "query.q"]}. Строку str(exc) клиенту не отдают, в ней внутренние подробности

Для бизнес-исключений регистрируют обработчик на свой класс (@app.exception_handler(InsufficientFunds)), и сервисный слой не знает про HTTP. Обработчик для HTTPException документация советует вешать на класс из starlette.exceptions: тогда он поймает и то, что поднимает сам Starlette. Стандартные обработчики можно переиспользовать из fastapi.exception_handlers

OpenAPI и /docs

Схему FastAPI собирает из того, что уже знает о маршрутах: путь, метод, параметры и их источники, JSON Schema моделей из Pydantic, status_code, tags, докстринг, схемы безопасности из зависимостей. Модели складываются в components/schemas, каждому маршруту с параметрами добавляется ответ 422 со схемой HTTPValidationError. Версия схемы — OpenAPI 3.1.0

Собирается она лениво, при первом запросе к /openapi.json, и кэшируется в app.openapi_schema. /docs (Swagger UI) и /redoc только читают этот JSON. openapi_url=None отключает и схему, и документацию, так часто делают на проде публичного API

Схема знает только объявленное. HTTPException(404) из тела обработчика в неё не попадёт, его описывают через responses={404: {...}}. По схеме часто генерируют клиентов, и неописанные ответы потом всплывают у фронтенда

include_router

Маршруты раскладывают по APIRouter и собирают через app.include_router(router, prefix="/users"). До 0.137.0 include_router копировал маршруты в момент вызова, и маршрут, добавленный в роутер позже, в приложение не попадал. С 0.137.0 копирования нет: FastAPI хранит, какой роутер какой включает, и порядок больше не важен. Цена — router.routes теперь дерево с промежуточными объектами, а не плоский список APIRoute, и код, который его обходил и менял, может сломаться

🛠️ На практике

Lifespan создаёт пул, зависимость с yield выдаёт соединение на запрос, вторая зависимость берёт ту же сессию, модель ответа прячет пароль. Пул ненастоящий, чтобы пример запускался без базы:

Python · Приложение с lifespan, сессией и TestClient

from contextlib import asynccontextmanager
from typing import Annotated

from fastapi import Depends, FastAPI, HTTPException, Request
from fastapi.testclient import TestClient
from pydantic import BaseModel


class FakePool:
    def __init__(self):
        self.opened = 0

    def acquire(self):
        self.opened += 1
        return f"conn-{self.opened}"


@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.pool = FakePool()       # до первого запроса
    print("lifespan: пул создан")
    yield
    print("lifespan: пул закрыт")     # после последнего запроса


app = FastAPI(lifespan=lifespan)


def get_session(request: Request):
    conn = request.app.state.pool.acquire()
    print(f"  открыта {conn}")
    try:
        yield conn
    finally:
        print(f"  закрыта {conn}")


Session = Annotated[str, Depends(get_session)]


def get_current_user(session: Session) -> str:
    return "alice"


class UserIn(BaseModel):
    name: str
    password: str


class UserOut(BaseModel):
    id: int
    name: str


@app.post("/users", response_model=UserOut, status_code=201)
def create_user(user: UserIn, session: Session,
                author: Annotated[str, Depends(get_current_user)]):
    print(f"  хендлер: session={session}, author={author}")
    # возвращаем больше полей, чем в UserOut: password отфильтруется
    return {"id": 1, "name": user.name, "password": user.password}


@app.get("/users/{user_id}", response_model=UserOut)
def read_user(user_id: int, session: Session):
    raise HTTPException(status_code=404, detail="user not found")


with TestClient(app) as client:   # with запускает lifespan
    r = client.post("/users", json={"name": "Bob", "password": "s3cret"})
    print(r.status_code, r.json())
    r = client.get("/users/42")
    print(r.status_code, r.json())
    r = client.get("/users/abc")
    print(r.status_code, r.json())

Вывод на FastAPI 0.162.4, Pydantic 2.14.3, Python 3.13 (ответ 422 сокращён):

lifespan: пул создан
  открыта conn-1
  хендлер: session=conn-1, author=alice
  закрыта conn-1
201 {'id': 1, 'name': 'Bob'}
  открыта conn-2
  закрыта conn-2
404 {'detail': 'user not found'}
  открыта conn-3
  закрыта conn-3
422 {'detail': [{'type': 'int_parsing', 'loc': ['path', 'user_id'], 'msg': 'Input should be a valid integer, ...', 'input': 'abc'}]}
lifespan: пул закрыт

Что здесь видно:

  • get_session нужна и обработчику, и get_current_user, а соединение открылось одно, conn-1: это кэш зависимости
  • password в ответ не попал, его отфильтровала UserOut
  • finally сработал и при 404: исключение из обработчика прошло через yield
  • на /users/abc соединение открылось, хотя ответ 422. Зависимость без своих ошибок выполняется до того, как FastAPI отдаст ошибки валидации, поэтому её побочные эффекты случаются и на невалидном запросе
  • без with TestClient(app) lifespan не запустится, и app.state.pool не будет

Свежий Starlette при импорте TestClient пишет DeprecationWarning и советует пакет httpx2 вместо httpx, на работу примера это не влияет. В тестах get_session подменяют через app.dependency_overrides, подробнее — на странице про тесты

⚠️ Где ошибаются

Commit после yield. yield session и следом await session.commit() выглядит аккуратно, но по умолчанию выполняется, когда ответ уже ушёл. Commit упал на уникальном индексе, клиент получил 201, записи нет

Одна модель на вход и на выход. def create(user: User) -> User с полем password вернёт пароль клиенту и покажет его в схеме ответа

on_event рядом с lifespan. Завели lifespan для нового пула, а старый @app.on_event("startup") с подключением к Redis остался. Он молча перестаёт вызываться, и сервис падает на первом обращении к Redis

Авторизация в middleware. Middleware не знает, какой маршрут публичный, и появляется список путей-исключений, который расходится с роутером. HTTPException(401) оттуда превращается в 500. Проверку токена делают зависимостью на роутере

Проглоченное исключение. except Exception: await session.rollback() без raise в зависимости: клиент получает 500, а в логах пусто

🎯 Вопросы с собеседований

Как устроены зависимости FastAPI и зачем зависимости с yield

Зависимость — функция или класс в Depends. FastAPI читает её сигнатуру как сигнатуру обработчика, поэтому у неё свои параметры и свои зависимости, и получается дерево. За запрос каждая зависимость вызывается один раз: общий get_session у обработчика и get_current_user даст одну сессию. Зависимость с yield открывает ресурс до yield и закрывает после, даже если обработчик упал. По умолчанию код после yield выполняется после отправки ответа, а scope="function" с 0.121.0 закрывает ресурс до отправки, поэтому commit после yield в режиме по умолчанию опасен

Что такое lifespan и чем он лучше on_event

Асинхронный контекстный менеджер в FastAPI(lifespan=...): до yield код выполняется до первого запроса, после — при остановке. Там создают пулы и клиенты и кладут в app.state или отдают словарём в request.state. Открытие и закрытие ресурса стоят рядом, без глобалов, и async with закроет уже открытое, если старт упал. on_event устарел, в Starlette 1.0 удалён, а при переданном lifespan его обработчики вообще не вызываются

Middleware или зависимость: что выбрать для авторизации, логирования, транзакции

Middleware видит каждый запрос, включая 404, но не знает маршрута и не передаёт значение в обработчик. В нём логирование, request id, метрики, CORS. Авторизация — зависимость: обработчику нужен пользователь, права у маршрутов разные, схема безопасности попадает в OpenAPI, а HTTPException из зависимости становится нормальным 401. Транзакция тоже зависимость, но commit делают до отправки ответа

Почему FastAPI отвечает 422 и как поменять формат ошибки

Запрос не прошёл валидацию по объявленным типам: параметр пути не число, в теле нет поля. FastAPI поднимает RequestValidationError, стандартный обработчик отдаёт {"detail": [...]} с type, loc, msg, input. Формат меняют через @app.exception_handler(RequestValidationError), собирая ответ из exc.errors(), можно и с другим кодом, например 400. Невалидный ответ обработчика — это ResponseValidationError и 500

Как FastAPI строит OpenAPI-схему

Из объявленного в коде: обходит маршруты и берёт путь, метод, параметры, JSON Schema моделей из Pydantic, коды ответов, теги и схемы безопасности из зависимостей. Модели кладутся в components/schemas, к маршрутам с параметрами добавляется 422. Схема строится лениво при первом запросе к /openapi.json и кэшируется, /docs просто читает этот JSON. HTTPException(404) из тела функции в схему не попадёт, его описывают через responses=

Обработчик на def или на async def

def FastAPI запускает в пуле потоков AnyIO (по умолчанию 40 потоков), async def — прямо в цикле событий, поэтому синхронный драйвер внутри async def блокирует весь сервис. Подробно — на странице «Блокирующий код в async» в модуле про конкурентность

📚 Что почитать

  • Dependencies with yield — когда выполняется код после yield, scope="function" и почему нельзя глотать исключения
  • Advanced Dependencies — история зависимостей с yield по версиям: 0.106.0, 0.110.0, 0.118.0, 0.121.0
  • Lifespan Events — lifespan, устаревший on_event и почему их нельзя смешивать
  • Handling Errors — свои обработчики для HTTPException и RequestValidationError
  • Release notes FastAPI — что ломалось между версиями, в том числе Pydantic v1 в 0.128.0 и include_router в 0.137.0