Driving и driven стороны

Две стороны гексагона

Оригинальное описание Cockburn размещало адаптеры на двух различных сторонах, и асимметрия имеет значение:

Driving-сторона (левая / primary) — акторы, инициирующие взаимодействие с приложением. Driving-адаптер вызывает primary port, чтобы заставить приложение что-то сделать. HTTP-контроллер получает POST и вызывает confirmOrder. CLI получает команду и вызывает confirmOrder. Автоматизированный тест вызывает confirmOrder. Каждый driving-адаптер переводит собственный формат входных данных в вызов метода порта.

Driven-сторона (правая / secondary) — инфраструктура, которую приложение активирует для выполнения своей работы. Driven-адаптер реализует secondary port. Приложение вызывает IOrderRepository.save(order) — Postgres-адаптер отвечает. Приложение вызывает IPaymentGateway.charge(amount) — Stripe-адаптер отвечает. Приложение вызывает IEmailNotifier.send(message) — SendGrid-адаптер отвечает.

Критическая асимметрия: driving-сторона вызывает приложение; driven-сторона вызывается приложением. Обе стороны опосредованы портами. Но направление инициирования противоположно.

Domain в центре

Domain находится в центре гексагона, окружённый с обеих сторон портами, которыми он владеет. Это структурное следствие применения Dependency Inversion Principle (unit 02) на архитектурном уровне: высокоуровневая политика (domain) владеет абстракциями; низкоуровневые механизмы (адаптеры) зависят от этих абстракций, чтобы подключиться.

На B2B-платформе domain определяет:

// Primary ports (что domain предлагает)
interface OrderConfirmationPort {
  confirmOrder(orderId: string, approverId: string): Promise<ConfirmationResult>;
}
interface InvoiceGenerationPort {
  generateInvoice(orderId: string): Promise<InvoiceId>;
}

// Secondary ports (что domain требует)
interface IOrderRepository {
  findById(id: string): Promise<Order | null>;
  save(order: Order): Promise<void>;
}
interface IPaymentGateway {
  charge(customerId: CustomerId, amount: Money): Promise<ChargeResult>;
}
interface IEmailNotifier {
  send(recipient: Email, subject: string, body: string): Promise<void>;
}

Все эти интерфейсы живут в пакете domain. Ни один из них не импортирует HTTP, Stripe, Postgres или SendGrid. Domain не имеет никаких знаний о технологических выборах внешнего мира. Он знает только, что ему нужно (secondary ports) и что он предоставляет (primary ports).

HTTP, CLI и тест-драйвер — все вызывают один и тот же primary port

Одно из наиболее ценных свойств driving-стороны: она нормализует все точки входа к одному и тому же интерфейсу порта. Use case подтверждения определён один раз на primary port. Любая технология, способная сформировать необходимые доменные параметры, может его вызвать.

// HTTP driving adapter
class HttpOrderController {
  constructor(private port: OrderConfirmationPort) {}

  async post(req: Request): Promise<Response> {
    const result = await this.port.confirmOrder(
      req.params.orderId,
      req.body.approverId
    );
    return result.success
      ? Response.json({ status: 'confirmed' }, { status: 200 })
      : Response.json({ error: result.reason }, { status: 422 });
  }
}

// CLI driving adapter
class CliOrderConfirmCommand {
  constructor(private port: OrderConfirmationPort) {}

  async run(args: string[]): Promise<void> {
    const [orderId, approverId] = args;
    const result = await this.port.confirmOrder(orderId, approverId);
    console.log(result.success ? 'Confirmed' : `Failed: ${result.reason}`);
  }
}

// Test driving adapter — фреймворк не нужен, только порт
async function confirmOrderViaPort(
  port: OrderConfirmationPort,
  orderId: string,
  approverId: string
): Promise<ConfirmationResult> {
  return port.confirmOrder(orderId, approverId);
}

Логика подтверждения выполняется идентично независимо от того, является ли вызывающим HTTP-запрос, CLI-команда или тест. Тест-драйвер максимально прост: прямой вызов. Никакого HTTP-клиента, номера порта или запуска сервера. Это доступно именно потому, что primary port принадлежит domain и говорит на языке domain.

Driven-сторона: secondary ports инвертируют зависимость от infrastructure

Driven-сторона — это место, где DIP из unit 02 становится конкретным. Domain определяет, что ему нужно — IPaymentGateway, IOrderRepository — в собственном пакете, на языке domain. Stripe-адаптер реализует IPaymentGateway; он зависит от определения интерфейса domain. Postgres-адаптер реализует IOrderRepository; он зависит от определения интерфейса domain.

Направление source-code зависимости на driven-стороне то же, что и на driving-стороне: всегда внутрь, к domain.

// Secondary port — определён в пакете domain
// domain/ports/IPaymentGateway.ts
interface IPaymentGateway {
  charge(customerId: CustomerId, amount: Money): Promise<ChargeResult>;
  refund(chargeId: ChargeId, amount: Money): Promise<RefundResult>;
}

// Driven adapter — определён в пакете infrastructure
// infra/payment/StripePaymentAdapter.ts
import { IPaymentGateway, ChargeResult, RefundResult } from '../../domain/ports/IPaymentGateway';
import Stripe from 'stripe';

class StripePaymentAdapter implements IPaymentGateway {
  private client = new Stripe(process.env.STRIPE_KEY!);

  async charge(customerId: CustomerId, amount: Money): Promise<ChargeResult> {
    const intent = await this.client.paymentIntents.create({
      amount: amount.inCents(),
      currency: amount.currency,
      customer: customerId.value,
    });
    return ChargeResult.fromStripeIntent(intent);
  }

  async refund(chargeId: ChargeId, amount: Money): Promise<RefundResult> {
    const refund = await this.client.refunds.create({
      payment_intent: chargeId.value,
      amount: amount.inCents(),
    });
    return RefundResult.fromStripeRefund(refund);
  }
}

StripePaymentAdapter импортирует из domain (IPaymentGateway). Domain не импортирует из StripePaymentAdapter. npm-пакет stripe — деталь адаптера: domain не имеет транзитивной зависимости от него. Это исправление истории из вступления: перемещение вызова Stripe за secondary port означает, что domain можно тестировать без Stripe, а смена процессора платежей сводится к написанию нового адаптера без изменения domain.