Гексагональная архитектура для пет-проектов: простой старт с Ports and Adapters

Представьте ситуацию: вы полгода пишете свой личный блог или трекер задач, наслаждаетесь процессом, а затем решаете заменить базу данных PostgreSQL на MongoDB. В традиционном монолите вам придется лезть в каждый файл, переписывать десятки запросов и бояться сломать бизнес-логику. А теперь представьте, что это изменение требует всего лишь создания нового файла-адаптера. Это не магия, это Гексагональная архитектура, известная также как Архитектура портов и адаптеров. Многие боятся её использовать в маленьких пет-проектах, считая излишеством для энтерпрайза. Но я скажу вам секрет: именно пет-проекты - идеальное поле для оттачивания этих навыков.

Суть идеи простым языком

В основе этого подхода лежит простая идея: ядро приложения должно жить своей жизнью и знать только о своих правилах. Все внешнее окружение - базы данных, HTTP-серверы, мессенджеры, файловые системы - должно находиться за пределами этого ядра. Представьте свою программу как USB-устройство. Сама флешка (ядро) не знает, в какой порт вы её воткнете. Она просто предоставляет интерфейс для обмена данными. Порт - это разъем, по которому происходит взаимодействие, а адаптер - это шнур, который соединяет ваше устройство с конкретной системой.

Когда вы проектируете пет-проект, такой подход снимает головную боль будущих изменений. Вы можете начать с консоли, добавить веб-интерфейс потом, и даже подключить новый способ оплаты - всё это будет работать поверх одного и того же кода бизнес-логика.

Зачем это нужно в пет-проекте?

Часто говорят: "На кой мне сложность ради простого калькулятора калорий". Вопрос правильный. Однако главная ценность гексагональной архитектуры в пет-проекте - не масштабирование до миллионов юзеров, а обучение дисциплине. Когда вы учитесь разделять зависимости, вы начинаете писать код, который легче тестировать и читать. Ваша программа превращается из набора "спагетти" в набор модулей, с которыми можно безопасно экспериментировать.

Вы сможете легко менять инструменты. Сегодня вы используете Spring Boot и JDBC, завтра захотели перейти на легковесный функциональный стек или микросервисы? Адаптеры позволяют сделать это быстро. В реальном мире такая гибкость экономит сотни часов поддержки, а в хобби-проекте она дает вам свободу экспериментировать без чувства вины за "грязный рефакторинг".

Как выглядят компоненты на практике

Давайте посмотрим, как это выглядит на примере простого сервиса регистрации пользователей. У нас есть три основных части, и важно понимать их границы.

1. Домен (Domain Layer)

Это сердце вашего приложения. Здесь живут сущности (Entities) и их поведение. Никаких аннотаций JPA (@Entity, @OneToMany), никаких классов Request/Response из Spring, никаких SQL-строк. Только чистые классы языка программирования. Например, объект User может иметь методы валидации своего email, но никогда не знает, где этот User хранится.

2. Прикладной слой (Application Layer)

Он организует работу домена. Тут мы объявляем "интерфейсы" - порты. Это абстракции, которые описывают, ЧТО нужно сделать приложению, но не КАК. Например, интерфейс UserRepository говорит: "Я могу найти пользователя по ID и сохранить нового". В этом слое лежат сервисы, которые используют эти порты для выполнения бизнес-процессов.

3. Инфраструктура (Infrastructure Layer)

Здесь живёт "музыка" - конкретные реализации ваших интерфейсов. Если ваш порт просит базу данных, здесь вы подключаете Hibernate или MyBatis. Если нужен HTTP - здесь ваш контроллер. Это внешний мир, который "затаскивает" данные внутрь через ваши порты. Главное правило: инфраструктура зависит от домена, а не наоборот.

Пример реализации кода

Давайте набросаем, как это выглядит в коде. Это поможет увидеть структуру глазами разработчика. Допустим, мы используем Java, но принципы универсальны.

// Порт (интерфейс в слое приложения)
public interface UserPort {
    User getUserById(Long id);
    void saveUser(User user);
}

// Реализация порта (Адаптер в инфраструктуре)
public class SqlUserAdapter implements UserPort {
    private Connection dbConnection;
    
    public User getUserById(Long id) {
        // Тут сложный SQL, транзакции, обработчики ошибок
        return ...;
    }
}

Обратите внимание: когда приходит время менять базу данных, вы не трогаете интерфейс UserPort и не меняете логику в сервисах. Вы просто создаете класс NoSqlUserAdapter, который реализует тот же интерфейс. В системе инъекции зависимостей вы просто указываете новый класс. Для остальной программы ничего не изменилось.

Плюсы и минусы для новичка

Нельзя скрывать, что путь не лишен трудностей. Начиная проект с нуля, вы теряете часть скорости. Вместо того чтобы написать всё в одном файле за час, вы тратите время на создание структуры папок, интерфейсов и классов. Для совсем маленьких проектов это кажется избыточным.

• Плюсы: Легкое тестирование. Вы можете передать вместо реального SQL-адаптера мок, который возвращает фиктивные данные. Это позволяет писать unit-тесты за секунды.
• Плюсы: Четкая структура. Новым людям в проекте (или самому себе через полгода) проще понять, куда что добавлять.
• Минусы: Сложность входа. Нужно думать про архитектуру до начала активной разработки.
• Минусы: Избыточность для скриптов. Если проект живет один день, лучше писать монокласс.

Типичные ошибки внедрения

Один из главных рисков - превратить архитектуру в религию. Не нужно создавать пустые пакеты, если они вам сейчас не нужны. Начните с определения ядра. Определите одну ключевую операцию (например, создание заказа) и вынесите её в сервис. Остальное можно постепенно переносить.

Другая ловушка - пытаться сделать все адаптеры одинаково сложными. Адаптер для лога может быть проще, чем адаптер для платежной системы. Слушайте задачи бизнеса, а не абстрактные паттерны.