архитектура

Гексагональная архитектура: как изолировать бизнес-логику от внешних технологий и зависимостей

Узнайте, как гексагональная архитектура помогает изолировать бизнес-логику от внешних зависимостей. Мы разберем принципы работы портов и адаптеров для создания гибких систем.

Введение

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

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

Изоляция ядра: доменная логика как центр системы

В основе гексагональной архитектуры лежит принцип, согласно которому бизнес-логика является независимой от технических деталей. Ядро системы (Domain Layer) должно описывать «что» делает приложение, не заботясь о том, «как» оно взаимодействует с внешним миром. Это означает, что правила расчета налогов, логика изменения статусов заказов или условия регистрации пользователя не должны зависеть от того, используется ли для хранения данных PostgreSQL, Redis или просто текстовый файл.

Для достижения этой изоляции необходимо строго соблюдать три архитектурных ограничения:

  • Независимость инфраструктуры: Ядро не знает о существовании веб-фреймворков (Express, Spring), брокеров сообщений (RabbitMQ) или конкретных драйверов БД. Любое внешнее взаимодействие происходит через абстракции — порты.
  • Разделение сущностей и сценариев: Важно четко различать Entities (объекты с состоянием и инвариантами) и Use Cases (сервисы, координирующие поток данных). Сущность отвечает за внутреннюю согласованность данных, а Use Case — за выполнение конкретного бизнес-сценария.
  • Запрет на внешние зависимости: Внутри папки с доменомной логикой запрещено импортировать любые библиотеки сторонних разработчиков, если они не являются частью чистого языка программирования (например, стандартные коллекции или базовые типы данных).

Пример правильного подхода в коде демонстрирует использование интерфейса вместо прямой зависимости от репозитория:

# Доменная модель (Entity) - чистый код без зависимостей
class Order:
    def __init__(self, id: str, total_amount: float):
        self.id = id
        self.total_amount = total_amount

    def apply_discount(self, percentage: float):
        if 0 <= percentage <= 100:
            self.total_amount *= (1 - percentage / 100)

# Порт (Интерфейс) - описание намерения
from abc import ABC, abstractmethod

class OrderRepository(ABC):
    @abstractmethod
    def save(self, order: Order) -> None:
        pass

# Use Case - координация логики
class ApplyDiscountUseCase:
    def __init__(self, repository: OrderRepository):
        self.repository = repository  # Зависимость от интерфейса, а не реализации

    def execute(self, order_id: str, discount: float):
        order = self.repository.get_by_id(order_id)
        order.apply_discount(discount)
        self.repository.save(order)

Такой подход обеспечивает высокую тестируемость (возможность легко подменять репозитории моками), устойчивость к изменениям технологий и позволяет команде фокусироваться на развитии продукта, а не на борьбе с побочными эффектами обновлений библиотек.

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

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

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

Driving Ports определяют способы, которыми внешние системы или пользователи могут инициировать действия в приложении. Когда внешний актер «возбуждает» систему, он взаимодействует с входным портом. К ним относятся:

  • REST API эндпоинты;
  • Команды командной строки (CLI);
  • Обработчики сообщений из очередей (RabbitMQ, Kafka);
  • Планировщики задач (Cron jobs).

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

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

Driven Ports описывают зависимости приложения от внешних ресурсов и сервисов. Когда ядру необходимо выполнить действие, выходящее за пределы его ответственности — сохранить данные в БД, отправить письмо или вызвать сторонний API — оно обращается к выходному порту.

Типичные примеры Driven Ports:

  • Repository: для работы с базами данных;
  • Gateway: для интеграции со сторонними платежными системами или сервисами доставки;
  • Notification Service: для отправки уведомлений.

Интерфейсы и слабая связанность

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


// Driven Port (Определен внутри ядра)
interface UserRepository {
    public function save(User $user): void;
}

// Адаптер (Находится снаружи ядра, в слое инфраструктуры)
class SqlUserRepository implements UserRepository {
    private $dbConnection;

    public function __name-save(User $user): void {
        // Техническая реализация записи в MySQL/PostgreSQL
        $this->dbConnection->execute("INSERT INTO users ...");
    }
}

Такой подход реализует Принцип инверсии зависимостей (DIP): высокоуровневая бизнес-логика не зависит от низкоуровневых деталей. Если вам нужно сменить базу данных или заменить провайдера уведомлений, вы просто создаете новый адаптер и внедряете его в систему через порт, не меняя ни единой строчки кода в доменном слое.

Адаптеры: реализация технических деталей

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

Входные адаптер: обработка входящих событий

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

  • HTTP/REST: Обработка маршрутов, парсинг JSON, валидация заголовков.
  • CLI (Command Line Interface): Парсинг аргументов командной строки и вывод статусов в консоль.
  • Message Brokers: Потребление сообщений из Kafka или RabbitMQ, где адаптер отвечает за десериализацию данных перед передачей в сервис.
// Пример входного адаптера для HTTP (Express)
class CreateOrderHttpAdapter {
    constructor(private createOrderUseCase: CreateOrderUseCase) {}

    async handleRequest(req: Request, res: Response) {
        const command = OrderCommand.fromDto(req.body); // Маппинг из DTO в команду
        try {
            const result = await this.createOrderUseCase.execute(command);
            res.status(201).json(result);
        } catch (error) {
            res.status(400).send(error.message);
        }
    }
}

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

Выходные адаптеры реализуют побочные эффекты системы. Они принимают данные от доменной логики и транслируют их в конкретные технические хранилища или внешние сервисы.

  • Базы данных: Реализация портов для PostgreSQL (SQL), MongoDB (NoSQL) или Redis. Адаптер скрывает детали SQL-запросов от ядра.
  • Внешние API: Интеграция с платежными шлюзами, сервисами рассылки или системами аутентификации.
  • Файловые системы: Загрузка документов в S3-хранилище или локальную директорию.

Роль Dependency Injection и инверсии зависимостей (DIP)

Ключевой принцип, позволяющий архитектуре «шестиугольников» работать эффективно — Dependency Inversion Principle (DIP). Высокоуровневые модули (бизнес-логика) не должны зависеть от низкоуровневых деталей (драйверов БД или HTTP-клиентов). Вместо этого оба типа модулей должны зависеть от абстракций — портов.

Механизм Dependency Injection (DI) обеспечивает сквозную связку этих компонентов. При запуске приложения контейнер зависимостей «впрыскивает» конкретную реализацию адаптера в сервис, который требует соответствующий порт. Это позволяет:

  1. Легко заменять БД (например, использовать In-Memory хранилище для тестов и PostgreSQL для продакшена).
  2. Изолировать ошибки инфраструктуры: сбой в драйвере базы данных не должен менять логику расчета стоимости заказа.
  3. Параллельно разрабатывать разные части системы разными командами через согласованные интерфейсы.
// Пример инверсии зависимостей (DIP)
// Ядро зависит от абстракции (Порта), а не от реализации
class OrderService {
    constructor(private orderRepository: IOrderRepository) {} // Порт
}

// Адаптер — конкретная реализация, которая внедряется извне
class SqlOrderRepository implements IOrderRepository {
    async save(order: Order): Promise<void> {
        // Технические детали работы с SQL здесь
        await db.query('INSERT INTO orders ...', [order]);
    }
}

// Сборка системы (Composition Root)
const repository = new SqlOrderRepository(); 
const service = new OrderService(repository); // DI в действии

Практические нюансы: маппинг данных и сложность

Переход к гексагональной архитектуре неизбежно поднимает вопрос о стоимости владения кодом. Основным практическим вызовом здесь становится дублирование моделей. Чтобы обеспечить полную изоляцию слоев, данные должны проходить через несколько трансформаций:

  • DTO (Data Transfer Objects): структуры для сериализации/десериализации данных из внешних источников (JSON, XML).
  • Domain Entities: объекты, содержащие бизнес-логику и инварианты системы. Они не должны зависеть от библиотек работы с БД или сетевых фреймворков.
  • Persistence Models: структуры, оптимизированные под конкретную схему базы данных (например, ORM-сущности).

На первый взгляд это кажется избыточным, но такая строгость необходима для предотвращения «просачивания» технических деталей в бизнес-логику. Рассмотрим пример маппинга на языке TypeScript:


// Persistence Layer (TypeORM/Prisma)
interface UserEntity {
  id: string;
  fullName: string;
  passwordHash: string; // Техническое поле, не должно быть в домене
}

// Domain Layer (Pure Logic)
class User {
  constructor(public readonly id: string, public readonly name: string) {}
}

// Mapping logic (Adapter layer)
function mapToDomain(entity: UserEntity): User {
  return new User(entity.id, entity.fullName);
}

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

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

  1. Мы создаем Mock реализации порта (например, `UserRepository`).
  2. Передаем этот мок в сервис/интерфейс использования.
  3. Тестируем детерминированное поведение ядра: если порт вернул данные X, ядро должно выполнить действие Y.

Это позволяет достичь 100% покрытия критических путей логики за миллисекунды, что невозможно при интеграционном тестировании через реальные адаптеры.

Заключение

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

При выборе между Clean Architecture и Hexagonal Architecture стоит помнить, что они во многом синергичны. Если гексагональная архитектура фокусируется на структуре взаимодействия системы с внешним миром, то Clean Architecture предлагает детальную организацию слоев внутри ядра. В долгосрочной перспективе внедрение этих принципов гарантирует высокую поддерживаемость (Maintainability) кода: проект становится более тестируемым и модульным, что позволяет команде разработчиков концентрироваться на бизнес-ценности продукта, а не на борьбе с техническим долгом или сложностью инфраструктурных зависимостей.

Read next

Как проектировать отказоустойчивые PHP системы через архитектуру исключений

Узнайте, как перейти от реактивного исправления багов к системному проектированию механизмов обработки сбоев в PHP. Мы разберем создание кастомных исключений и использование стандартов PSR-3 для обеспечения стабильности продакшена.
PKirillW