ListIssuesSuggestions1DiscussionsInsights

🧙 Садовник: уточнил шаги, добавил проверки и обоснования. Примите, если полезно.

#1
open+7−15proposed by gardener · Aug 8, 2026 · based on v1
ConversationChecksProposed changes22Result
Result · becomes v2
•
Начните с плоской структуры для небольших скриптов

Размещайте все файлы (main.py, models.py, database.py) в корне проекта. Подходит для прототипов, автоматизаций и сервисов на пару эндпоинтов.

Why: Не надо стыдиться плоской структуры в маленьком проекте. Избыточная архитектура на вырост создаёт лишний шум.
  • –Проверить, что количество файлов в корне не превышает 10-15
  • –Убедиться, что над проектом не работают одновременно несколько разработчиков
•
Перейдите к слоистой структуре по техническим ролям

Группируйте файлы по их техническому назначению: models/, schemas/, services/, routers/. Это логичный шаг при выходе за рамки прототипа.

Why: Слоистая структура наглядно демонстрирует разделение ответственности и легко понятна новичкам.
  • –Проверить явность направления импортов между слоями
  • –Убедиться, что бизнес-логика не протекает в слой роутов
•
Группируйте код по фичам при росте функциональности

Создавайте отдельные модули под части предметной области (users/, products/, orders/), размещая слои внутри каждой фичи.

Why: Группировка по фичам локализует изменения: для добавления или удаления фичи работа происходит внутри одной папки.
  • –Проверить, что фичи не зависят друг от друга напрямую без четкого интерфейса
  • –Убедиться, что общение между фичами происходит через сервисы или события
Netflix DispatchFastAPI Best Practices
•
Внедрите гексагональную архитектуру с портами и адаптерамиRecommended

Отделите бизнес-логику в центр (domain/), описав внешние зависимости через интерфейсы-порты, а базы данных и фреймворки — через адаптеры.

Why: Инверсия зависимостей позволяет тестировать core-логику без запуска баз данных или сторонних сервисов.
  • –Проверить, что доменная логика не содержит импортов SQLAlchemy, FastAPI или requests
  • –Написать unit-тесты для домена с использованием memory-адаптеров
Алистер Кокберн о гексагональной архитектуре
•
Примените чистую архитектуру для сложной бизнес-логикиRecommended

Организуйте проект концентрическими слоями: сущности (entities), сценарии использования (use_cases), адаптеры и внешние фреймворки. Зависимости направлены строго внутрь.

Why: Защищает критически важные бизнес-правила от изменений во внешних библиотеках и фреймворках.
  • –Проверить соблюдение Dependency Rule: внутренние слои ничего не знают о внешних
  • –Убедиться, что use_case принимает и возвращает DTO или entities, а не ORM-модели
Роберт Мартин о чистой архитектуре
•
Изолируйте модули в формате модульного монолитаRecommended

Скомбинируйте подход по фичам с жестким ограничением видимости: каждый модуль имеет открытый api.py, а внутренности скрыты в internal/.

Why: Даёт преимущества четких границ без сложности и сетевых overhead-расходов микросервисной архитектуры.
  • –Настроить линтер или import-linter для запрета импортов из internal чужих модулей
  • –Проверить возможность выделения модуля в отдельный сервис
•
Выберите подходящую структуру под требования и масштабы проекта

Оцените размер команды, сложность предметной области и частоту изменений. Начните с более простой структуры и усложняйте её по мере роста.

Why: Преждевременное усложнение архитектуры замедляет разработку так же сильно, как и ее полное отсутствие.
  • –Сверить текущую сложность проекта с выбранной моделью
  • –Обсудить с командой правила импортов и границы модулей