Code Showcase — Backend (FastAPI)

Подборка файлов из production-проекта на FastAPI, демонстрирующих подход к архитектуре, качеству кода и тестированию.

Стек

• FastAPI + Pydantic v2 — REST API, валидация данных
• SQLAlchemy 2.x (async) — ORM, асинхронные сессии
• PostgreSQL — основная БД
• Redis — кеширование ответов эндпоинтов
• S3-совместимое хранилище — файлы, изображения
• Pillow — конвертация изображений в WebP
• pytest + pytest-asyncio + httpx — тестирование

Архитектура

Используется слоистая архитектура Repository → Service → Router:

routers/        ← HTTP-эндпоинты (тонкий слой, оркестрация)
services/       ← бизнес-логика (токены, email, кеш)
repositories/   ← доступ к данным (generic CRUD + специализированные)
schemas.py      ← Pydantic-схемы с кастомной валидацией
utils/          ← утилиты (файлы, изображения, кеш)
tests/          ← фикстуры и конфигурация тестов

Что демонстрируют файлы

Файл	Что показывает
repositories/base.py	Generic async CRUD-репозиторий
repositories/users.py	Специализированный репозиторий: eager loading, хеширование паролей, доменные исключения
routers/auth.py	Полный auth-flow: login, register, email verification, OTP, refresh tokens, autologin
services/auth_tokens.py	Сервис токенов: генерация, верификация, cleanup, вложенные транзакции
schemas.py	Продвинутая валидация Pydantic v2: BeforeValidator, computed_field, кастомные типы, нормализация путей
utils/cache.py	Декоратор кеширования с graceful degradation, сериализация Pydantic/ORM, инвалидация по паттерну
utils/file_storage.py	Async S3-интерфейс с автоматической конвертацией изображений в WebP
utils/file_validation.py	Валидация файлов: magic bytes, расширения, размеры, fallback без python-magic
utils/image_processing.py	Конвертация в WebP с ресайзингом, настраиваемым качеством и поддержкой альфа-канала
tests/conftest.py	Тестовая инфраструктура: PostgreSQL, xdist-параллелизация, safety guard от production, factory fixtures

Ключевые решения

• Async everywhere — все I/O операции асинхронные (DB, S3, Redis)
• Generic Repository — базовый CRUD с дженериками, специализация через наследование
• Доменные исключения в репозиториях вместо HTTPException — чистое разделение слоёв
• Graceful degradation — кеш деградирует при недоступности Redis без ошибок для пользователя
• Security: path traversal protection, magic bytes validation, production safety guard в тестах
• WebP conversion — автоматическая оптимизация изображений при загрузке

Примечание

Это выборка файлов, не полный проект. Импорты ссылаются на модули, не включённые в showcase (app.config, app.models, app.db и т.д.).