Содержание
В этой статье мы расскажем, как организовать каталоги, где хранить логику и почему стоит разделять API, сервисы и модели.
Корневой каталог
На верхнем уровне проекта обычно находятся:
- каталог src;
- файлы документации;
- миграции базы данных;
- shell-скрипты для запуска приложения, тестов и линтеров;
- файлы Docker и docker-compose;
- каталог с тестами;
- конфигурации линтеров, alembic, pre-commit хуков, GitLab и других инструментов;
- файлы зависимостей: requirements.txt, pyproject.toml;
- .env.example с примерами переменных окружения.
Важно: Python-кода в корне быть не должно. Всё приложение хранится в каталоге src.
Каталог src
Внутри src располагается весь исходный код. Здесь находятся точки входа — запуск самого приложения FastAPI, воркеров, планировщиков задач. А дальше проект разбивается на тематические каталоги:
- api — методы API, схемы запросов/ответов, обращение к сервисам.
- cli — команды для консоли, которые помогают автоматизировать рутинные задачи (например, создание суперпользователя или запуск миграций).
- config — подключение к БД, кэшу, очередям, админка и другие настройки FastAPI.
- middlewares — пользовательские middleware для логирования, аутентификации или кастомной обработки запросов и ответов.
- models — ORM-модели и работа с базой данных через менеджеры.
- services — бизнес-логика приложения.
- utils — вспомогательные функции и классы, которые переиспользуются в разных частях проекта.
Такой подход позволяет выстроить понятную последовательность взаимодействия:
api → service → models
API получает и валидирует данные → сервис обрабатывает бизнес-логику → модели общаются с базой данных.
Каталог api
Методы API должны быть максимально простыми: внутри функций нет бизнес-логики, только валидация данных и вызов сервисов.
Рекомендации:
- Всегда оборачивайте вызовы сервисов в try/except.
- Заполняйте summary, description, описывайте параметры и схемы — это позволит FastAPI автоматически строить удобную документацию.
- Для URL используйте kebab-case (например, /user-profile), а не snake_case или camelCase.
Каталог models
Каталог models делится на два подкаталога:
- dbo — для хранения ORM-моделей. Модели лучше группировать в файлах по смыслу: например, все сущности, связанные со структурой проектов, хранить в файле mod-els/dbo/projects.py.
- managers — для предоставления интерфейса взаимодействия сервисам с объектами в БД, инкапсулируя в себе ORM-запросы.
Рекомендации:
- Для каждой модели создаётся менеджер от BaseManager, базового класса, включаю-щего общие методы для работы с ORM.
- Запросы через ORM выполняются только внутри менеджеров.
- Методы менеджеров должны иметь docstring, желательно с SQL-запросом для наглядности.
- Класс модели также должен содержать docstring с бизнес-описанием сущности.
Каталог config
Включает в себя настройки приложения, получаемые из переменных окружения, ин-стансы клиентов для взаимодействия с различными внешними службами: postgres, redis, kafka, rabbitmq и т. д. А также настройки для swagger’а и админки.
Каталог config/admin внутри config хранит в себе настройки админки, например, с ис-пользованием библиотеки sqladmin. Для каждого раздела в админке — отдельный файл, наследуемый от BaseAdmin. Это позволяет поддерживать гибкую и масштаби-руемую структуру административного интерфейса.
Каталог services
Сервисы — это место для бизнес-логики. Здесь не должно быть прямых импортов мо-дулей из SQLAlchemy (кроме типизации параметров). Все публичные методы доку-ментируются docstring, для них пишутся автотесты.
Идея проста: сервисы отвечают только за бизнес-логику, а данные получают через модели. Отсутствие прямых ORM-запросов позволяет легко тестировать логику без обращения к БД и при необходимости заменить ORM.
Каталог cli
В этом каталоге в моих проектах находится реализация различных команд для кон-соли, которые помогают автоматизировать рутинные задачи (например, создание суперпользователя или запуск миграций).
Каталог middlewares
Здесь хранятся пользовательские middleware для логирования, аутентификации, ка-стомной обработки запросов и ответов, а также других задач.
Каталог utils
Небольшие вспомогательные функции и классы, которые переиспользуются в разных частях проекта. Ими могут являться например кастомные преобразования дат, уни-кальные именно для данного проекта, работа с другими типами данных, их преобра-зование.
Зачем всё это?
Такая архитектура решает три главные задачи:
- Масштабируемость — проект легко расширять без «спагетти-кода».
- Прозрачность — каждый каталог отвечает за свою зону ответственности.
- Качество кода — простая поддержка, предсказуемое поведение, понятные тесты и документация.
FastAPI сам по себе удобный фреймворк, но правильная архитектура превращает его в инструмент для серьёзных корпоративных приложений. Чёткое разделение кода по каталогам, использование сервисов и менеджеров моделей, документирование и ав-тотесты — всё это закладывает фундамент надёжного продукта.