⚡ 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в ответ не попал, его отфильтровалаUserOutfinallyсработал и при 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