Учебник FastAPI для начинающих

Программа курса

1. 1 Введение и асинхронность

   1. Что такое FastAPI и почему его выбирают

      Знакомство с FastAPI: ASGI, типы Python, автодокументация и почему фреймворк стал стандартом для API на Python в 2024-2025.

   2. Синхронность, асинхронность и event loop

      Как работает async/await в Python, что такое event loop, чем async def отличается от обычного def и почему это важно для FastAPI.

   3. async def и def обработчики: что выбрать

      Чем отличаются async def и обычные def обработчики в FastAPI, как работает threadpool для синхронного кода и как не заблокировать сервер.

   4. Первое приложение и запуск через uvicorn

      Создаём минимальное FastAPI-приложение, запускаем его через uvicorn, разбираем декораторы маршрутов и интерактивную документацию /docs.

2. 2 Эндпоинты и параметры

   1. Параметры пути и их валидация

      Path-параметры в FastAPI: как объявлять, как работает автоматическая конвертация типов, валидация через Path и порядок маршрутов.

   2. Query-параметры, значения по умолчанию и Annotated

      Query-параметры в FastAPI: обязательные и опциональные, значения по умолчанию, ограничения через Query и современный синтаксис Annotated.

   3. Тело запроса, методы и коды статусов

      Как принимать тело запроса через Pydantic-модели, чем отличаются GET/POST/PUT/PATCH/DELETE и как задавать коды статусов ответа.

   4. Заголовки, cookies и формы

      Как принимать HTTP-заголовки, cookies и данные форм в FastAPI через Header, Cookie и Form, и чем form-data отличается от JSON.

   5. Маршрутизация, теги и APIRouter

      Организация маршрутов в больших проектах: APIRouter, префиксы, теги, разбиение на модули и подключение через include_router.

3. 3 Pydantic: модели и валидация

   1. Pydantic v2: модели и валидация данных

      Что такое Pydantic-модели, как BaseModel валидирует и конвертирует данные, и что нового в Pydantic v2 с ядром на Rust.

   2. Field, ограничения и кастомные валидаторы

      Тонкая настройка полей Pydantic через Field, ограничения значений, и кастомная валидация через field_validator и model_validator в v2.

   3. Response-модели и разделение входа и выхода

      Зачем нужны response_model, как разделять модели входа и выхода, скрывать чувствительные поля и управлять сериализацией ответа.

   4. Вложенные модели, списки и опциональные поля

      Вложенные Pydantic-модели, списки объектов, словари и опциональные поля; как FastAPI валидирует сложные структуры данных.

4. 4 Зависимости (Dependency Injection)

   1. Dependency Injection и Depends

      Что такое внедрение зависимостей в FastAPI, как работает Depends, зачем оно нужно и как переиспользовать общую логику между эндпоинтами.

   2. Зависимости с yield и управление ресурсами

      Зависимости с yield в FastAPI: открытие и гарантированное закрытие ресурсов (сессий БД), аналогия с контекстным менеджером и порядок выполнения.

   3. Вложенные зависимости и зависимости класса

      Зависимости, которые сами зависят от других, классы как зависимости, и зависимости уровня роутера и приложения.

5. 5 База данных, ошибки и безопасность

   1. Lifespan: запуск и остановка приложения

      Жизненный цикл FastAPI-приложения через lifespan: подключение к БД при старте и закрытие при остановке, почему on_event устарел.

   2. Подключение базы данных через зависимости

      Интеграция базы данных в FastAPI: сессия как зависимость с yield, паттерн создания engine в lifespan и работа с SQLAlchemy.

   3. Обработка ошибок и HTTPException

      Как возвращать корректные ошибки в FastAPI: HTTPException, коды статусов, кастомные обработчики исключений и формат ответа об ошибке.

   4. Аутентификация: OAuth2, токены и JWT

      Безопасность в FastAPI: OAuth2PasswordBearer, выдача и проверка JWT-токенов, хеширование паролей и защита эндпоинтов через зависимости.

6. 6 Практика: продакшен-ready API

   1. Автодокументация: OpenAPI, Swagger и ReDoc

      Как FastAPI генерирует OpenAPI-схему из типов и моделей, чем отличаются Swagger UI и ReDoc и как обогащать документацию метаданными.

   2. Middleware, CORS и фоновые задачи

      Middleware для сквозной логики, настройка CORS для фронтенда и BackgroundTasks для отложенной работы после ответа в FastAPI.

   3. Тестирование FastAPI-приложений

      Как тестировать FastAPI: TestClient, pytest, переопределение зависимостей через dependency_overrides и изоляция базы данных в тестах.

   4. Структура проекта и подготовка к продакшену

      Как структурировать большой FastAPI-проект, настройки через переменные окружения, запуск в продакшене и развёртывание в Docker.

7. 7 Асинхронность и конкурентность

   1. async def против def: когда какой

      Когда писать роут как async def, а когда обычным def: как FastAPI запускает sync-обработчики в threadpool, почему блокирующий код в async-роуте — катастрофа, и про run_in_threadpool.

   2. Фоновые задачи: BackgroundTasks и когда нужен Celery

      Когда использовать BackgroundTasks FastAPI для лёгкой работы после ответа, в чём её ограничения и когда пора выносить задачи в очередь и Celery или другой воркер.

   3. Конкурентность и event loop

      Как один процесс FastAPI обслуживает тысячи запросов через event loop, что блокирует цикл и как ускорить независимые операции с помощью asyncio.gather.

   4. Потоковые ответы и WebSockets

      Когда отдавать данные потоком: StreamingResponse для больших ответов, Server-Sent Events для односторонних обновлений и WebSocket для двунаправленной связи в FastAPI.

8. 8 Pydantic v2 вглубь

   1. Кастомная валидация: field_validator и model_validator

      Кастомная валидация в Pydantic v2: декораторы field_validator и model_validator, режимы mode before/after, переиспользование проверок и AfterValidator через Annotated.

   2. Сериализация: model_dump, computed_field, алиасы

      Сериализация в Pydantic v2: model_dump и model_dump_json, by_alias, exclude/include, вычисляемые поля computed_field и кастомные сериализаторы через field_serializer.

   3. Вложенные и обобщённые модели

      Сложные структуры в Pydantic v2: вложенные модели и списки моделей, обобщённые (generic) модели с TypeVar и дискриминированные union по полю-тегу.

   4. Конфигурация: BaseSettings и model_config

      Конфигурация приложения в Pydantic v2: pydantic-settings и BaseSettings, чтение настроек из переменных окружения и .env, model_config, строгий режим strict и frozen-модели.

9. 9 Архитектура больших приложений

   1. APIRouter и структура проекта

      Разбиение FastAPI на роутеры через APIRouter, префиксы и теги, структура папок большого приложения, include_router, общие зависимости и ответы на уровне роутера.

   2. Middleware и порядок обработки

      Своя middleware в FastAPI, порядок выполнения (внешняя оборачивает внутренние), CORS и GZip, добавление заголовков и времени ответа X-Process-Time, отличие middleware от зависимостей.

   3. Зависимости вглубь: классы, yield, кэширование

      Продвинутые зависимости FastAPI: классы как зависимости, yield для управления ресурсами БД, под-зависимости, кэширование в рамках запроса (use_cache) и подмена через dependency_overrides в тестах.

   4. Обработка ошибок: exception handlers

      Обработка ошибок в FastAPI: HTTPException и заголовки, кастомные исключения, @app.exception_handler, перехват ошибок валидации RequestValidationError, единый формат ошибок для всего API.

10. 10 Тестирование и продакшен

    1. Тестирование FastAPI: TestClient и pytest

       Как тестировать FastAPI: TestClient и pytest-фикстуры, подмена зависимостей через dependency_overrides, изолированная тестовая база данных и асинхронные тесты на httpx.

    2. Деплой: uvicorn, gunicorn, воркеры

       Боевой деплой FastAPI: ASGI-сервер uvicorn, gunicorn с uvicorn-воркерами, сколько воркеров поднимать, запуск за обратным прокси nginx и контейнеризация в Docker.

    3. Производительность и кэширование

       Производительность FastAPI: где узкие места, кэширование ответов в Redis, пул соединений к БД, профилирование запросов и почему async-код должен быть неблокирующим.

    4. Безопасность в проде

       Оборонительная безопасность FastAPI в проде: правильный CORS по белому списку, security-заголовки, rate limiting, секреты через env и ограничение размера запроса.