Архитектура

Введение

PKirillW

• 5 min read

Введение

Гексагональная архитектура, также известная как Ports and Adapters, представляет собой подход к проектированию программного обеспечения, ориентированный на строгую изоляцию бизнес-логики от внешних систем. Основная идея заключается в том, что ядро приложения должно оставаться независимым от деталей реализации: баз данных, пользовательских интерфейсов, сторонних API или очередей сообщений. В этой схеме мир делится на внутреннюю область — чистое описание предметной области, и внешнюю среду, с которой приложение взаимодействует через четко определенные границы.

Применение данного подхода дает разработчикам ряд стратегических преимуществ. Во-первых, это обеспечивает независимость от технологий: замена одного хранилища данных на другое или смена веб-фреймворка не требует переписывания основной логики. Во-вторых, архитектура значительно упрощает тестирование, позволяя легко подменять реальные компоненты имитациями (mock-объектами). Наконец, такая структура способствует долговечности кода, делая систему более устойчивой к изменениям требований и облегчая масштабирование проекта в долгосрочной перспективе.

Цель данной статьи — перейти от теоретических концепций к практическому применению гексагональной архитектуры в реальных проектах. Мы подробно разберем принципы инкапсуляции бизнес-логики, роль портов как контрактов взаимодействия и механизмы работы адаптеров с инфраструктурой. Также мы обсудим нюансы тестирования и эксплуатации систем, построенных на основе этого подхода, чтобы вы могли эффективно внедрить эти практики в свою текущую разработку.

Ядро приложения: инкапсуляция бизнес-логики

В гексагональной архитектуре ядро является «внутренним кругом», который содержит уникальную ценность продукта — бизнес-правила и логику предметной области. Главный принцип здесь заключается в том, что ядро не должно зависеть ни от каких внешних технологий: баз данных, веб-фреймворков или систем очередей.

Для обеспечения этой независимости применяется Принцип инверсии зависимостей (DIP). Вместо того чтобы доменная логика обращалась к конкретному репозиторию SQL, она взаимодействует с абстракциями (портами). Это позволяет менять инфраструктурные детали без изменения кода бизнес-логики.

Внутри ядра мы четко разделяем ответственности:

  • Entities: объекты, содержащие данные и правила валидации конкретного сущности.
  • Use Cases (Application Services): оркестраторы, которые описывают сценарии взаимодействия с сущностями для достижения бизнес-цели.

Важным аспектом является чистота кода. Бизнес-логика должна быть максимально свободна от побочных эффектов (side effects). Любое взаимодействие с внешним миром — запись в БД, отправка email или получение текущего времени — должно происходить через порты. Это делает ядро детерминированным и легко тестируемым.

Для сложных операций, которые не могут быть инкапсулированы внутри одной сущности, используются доменные сервисы. Они управляют изменениями состояния между несколькими объектами, сохраняя при этом атомарность бизнес-правил:

# Пример: Use Case оркестрирует логику через доменный сервис
class CreateOrderUseCase:
    def __init__(self, order_repository: OrderRepositoryPort, payment_service: PaymentGateway):
        self.order_repo = order_repository
        self.payment_gateway = payment_service

    def execute(self, command: CreateOrderCommand) -> Order:
        # Логика создания заказа (Use Case)
        order = Order(items=command.items, status="PENDING")
        
        # Взаимодействие с внешним миром через порты/сервисы
        payment_result = self.payment_gateway.process(command.amount)
        
        if payment_result.success:
            order.markAsPaid()
            self.order_repo.save(order)
        return order

Такой подход гарантирует, что при переходе с PostgreSQL на MongoDB или замене REST-интерфейса на gRPC, код в центре ядра останется неизменным.

Порты как контракты взаимодействия

В гексагональной архитектуре порты выполняют роль интерфейсов или абстракций, которые определяют границы между внутренним ядром приложения (бизнес-логикой) и внешним миром. Они служат «контрактами»: они диктуют правила взаимодействия, не раскрывая деталей реализации ни внутри системы, ни снаружи.

Входные порты (Driving Ports)

Driving Ports — это точки входа в систему. Они описывают действия, которые внешние акторы (пользователи через UI, другие микросервисы или планировщики задач) могут инициировать в нашем приложении. В коде они чаще всего представлены как Service Interfaces.

// Пример входного порта для системы заказов
public interface OrderProcessingPort {
    OrderResponse placeOrder(PlaceOrderCommand command);
}

Выходные порты (Driven Ports)

Driven Ports — это абстракции для внешних ресурсов, с которыми ядро приложения должно взаимодействовать для выполнения своей работы. Это могут быть репозитории данных, платежные шлюзы или очереди сообщений. Ядро не знает о базе данных или протоколах передачи данных; оно лишь вызывает методы порта.

// Пример выходного порта для сохранения данных
public interface OrderRepository {
    void save(Order order);
}

// Пример выходного порта для уведомлений
public interface NotificationGateway {
    void sendConfirmation(String userId, String message);
}

Проектирование контрактов: типы данных

Критически важным аспектом проектирования портов является выбор типов данных. Чтобы сохранить чистоту архитектуры, порты не должны зависеть от внешних библиотек или моделей инфраструктуры (например, сущностей JPA/Hibernate или объектов JSON-библиотек).

  • Используйте Domain Models: Порт должен принимать и возвращать объекты из предметной области.
  • DTO для границ: Преобразование данных между входными портами (Request DTO) и внутренними моделями должно происходить на уровне адаптеров, а не внутри ядра.

Связь портов с Dependency Injection

Механизм Dependency Injection (DI) является «клеем», который соединяет порты с их конкретными реализациями в рантайме. В гексагональной архитектуре зависимость всегда направлена внутрь: ядро зависит от портов, а адаптеры зависят от ядра.

  1. Ядро определяет интерфейс (порт).
  2. Адаптер предоставляет конкретную реализацию этого интерфейса.
  3. DI-контейнер при запуске приложения внедряет нужную реализацию в соответствующие сервисы ядра.

Такой подход позволяет легко заменять реализации (например, заменить PostgreSQL на MongoDB или Mock-объект в тестах), не меняя ни одной строки кода бизнес-логики.

Адаптеры и интеграция с инфраструктурой

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

Входные адаптеры: точки входа

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

  • REST API контроллеры: Обрабатывают HTTP-запросы, парсят JSON/XML и передают данные в сервисы через соответствующие интерфейсы.
  • gRPC контроллеры: Обеспечивают высокопроизводительное межсервисное взаимодействие на базе Protocol Buffers.
  • CLI-интерфейсы: Позволяют запускать бизнес-логику напрямую из командной строки, что критически важно для внутренних инструментов и скриптов миграции.
  • Очереди сообщений (Message Brokers): Слушатели (consumers) в системах вроде Kafka или RabbitMQ принимают события и транслируют их во внутренние порты обработки.

Выходные адаптеры: взаимодействие с ресурсами

Выходные адаптеры реализуются для выполнения побочных эффектов системы. Ядро приложения не знает, как именно данные сохраняются или как вызывается внешний сервис; оно лишь взаимодействует с абстрактным портом:

  • Драйверы БД (SQL/NoSQL): Конкретные реализации репозиториев для PostgreSQL, MongoDB или Redis.
  • Внешние SDK и сторонние API: Интеграции с платежными шлюзами, сервисами рассылок или системами аналитики через официальные библиотеки разработчиков.

Стратегия маппинга данных

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

  • Входные данные преобразуются из DTO (Data Transfer Objects) в доменные модели перед попаданием в логику.
  • Результаты работы ядра конвертируются обратно в DTO или специфические структуры данных для передачи во внешние системы.
# Пример маппинга на уровне входного адаптера (REST)
def create_user_request(data: UserDTO) -> UserDomainModel:
    return UserDomainModel(
        id=data.external_id,
        username=data.login,
        email=data.contact_email
    )

# Пример маппинга на уровне выходного адаптера (SQL)
def to_db_entity(model: UserDomainModel) -> UserEntity:
    return UserEntity(
        uuid=str(model.id),
        name=model.username,
        is_active=True
    )

Унификация обработки ошибок

Адаптеры несут ответственность за обработку специфических исключений инфраструктуры (например, SQLException или TimeoutException). Вместо того чтобы пробрасывать их в ядро приложения, адаптер должен перехватывать их и преобразовывать в понятные для бизнеса ошибки:

  1. Перехват низкоуровневого исключения (например, "Connection Refused").
  2. Логирование технической детали для SRE-инженеров.
  3. Выброс доменного исключения (например, ServiceUnavailableException), которое ядро может обработать стандартным способом.

Тестирование и эксплуатация гексагональной архитектуры

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

Unit-тестирование домена: скорость и чистота

Поскольку ядро приложения (Domain) не зависит от баз данных, файловых систем или сетевых протоколов, unit-тесты для бизнес-логики выполняются максимально быстро. Мы тестируем чистые функции и объекты, используя моки (mocks) или заглушки (stubs) вместо реальных адаптеров.

# Пример теста доменного сервиса с использованием мока порта
def test_calculate_discount():
    # Мок репозитория, реализующий порт
    mock_repo = Mock(repository=UserRepository())
    service = DiscountService(user_repo=mock_repo)
    
    result = service.apply_seasonal_discount(user_id=10)
    assert result == 0.95  # Логика проверяется мгновенно без БД