Порты и адаптеры

Порт — это интерфейс, которым владеет домен; домен объявляет, что ему нужно, но никогда — что это предоставляет. Домен говорит «чтобы делать свою работу, мне нужно списать платёж» — и пишет интерфейс ровно под это, на языке домена, в коде домена:

// domain/ports/PaymentPort.ts — принадлежит домену, называет потребность домена
export interface PaymentPort {
  charge(amountCents: number, idempotencyKey: string): Promise<ChargeResult>;
}
export type ChargeResult = { ok: true; receiptId: string } | { ok: false; reason: string };

Заметь, чего здесь нет: ни Stripe, ни HTTP, ни API-ключа, ни типа из SDK. Порт говорит на словаре домена (amountCents, idempotencyKey, ChargeResult), а не вендора. Это и есть инверсия: высокоуровневая политика (домен) определяет абстракцию, а низкоуровневая деталь (Stripe) будет вынуждена подчиниться ей — а не наоборот. Порт — это контракт, от которого домен готов зависеть.

Адаптер — это реализация, живущая в инфраструктуре; он реализует порт домена и поглощает вендора. Существование Stripe теперь — факт, запертый в одном файле на краю:

// infrastructure/StripeAdapter.ts — реализует порт ДОМЕНА
import Stripe from "stripe";
import type { PaymentPort, ChargeResult } from "../domain/ports/PaymentPort";

export class StripeAdapter implements PaymentPort {
  constructor(private stripe: Stripe) {}

  async charge(amountCents: number, idempotencyKey: string): Promise<ChargeResult> {
    try {
      const intent = await this.stripe.paymentIntents.create(
        { amount: amountCents, currency: "usd", confirm: true },
        { idempotencyKey },
      );
      return { ok: true, receiptId: intent.id };
    } catch (e) {
      return { ok: false, reason: stripeReason(e) }; // перевод ошибок вендора в термины домена
    }
  }
}

Вся работа адаптера — перевод: на входе язык домена, на выходе вызовы вендора, ошибки вендора отображаются обратно в ChargeResult. Домен зависит от PaymentPort; StripeAdapter тоже зависит от PaymentPort (он его реализует) и от Stripe. Стрелка из инфраструктуры указывает внутрь, в домен. Stripe теперь лист, а не корень — заменяем написанием второго адаптера, и в домене не нужно трогать ничего.

Домен использует порт и остаётся в неведении о реализации — зависимость внедряется на краю. Сценарий использования написан целиком против порта:

// domain/PlaceOrder.ts — чистая политика, ноль знаний о вендоре
export class PlaceOrder {
  constructor(private payments: PaymentPort) {} // зависит от порта, не от Stripe

  async run(order: Order): Promise<OrderResult> {
    if (order.totalCents <= 0) return { status: "rejected", reason: "empty order" };
    const charge = await this.payments.charge(order.totalCents, order.id);
    if (!charge.ok) return { status: "declined", reason: charge.reason };
    return { status: "placed", receiptId: charge.receiptId };
  }
}

PlaceOrder — это стабильный центр. Его можно читать, осмыслять и менять, ни разу не открыв доки Stripe. Сборка — «в проде PaymentPort — это StripeAdapter» — происходит один раз, в корне композиции на самом внешнем краю:

// main.ts — единственное место, знающее обе стороны
const placeOrder = new PlaceOrder(new StripeAdapter(stripe));

Эта единственная строка — там, где абстрактное встречается с конкретным. Всё, что внутрь от неё, не зависит от вендора по построению.

Отдача конкретна: in-memory-адаптер делает домен тестируемым без сети, без ключей, без флакающих тестов. Поскольку домен зависит только от PaymentPort, подходит любая реализация — включая фейк, записывающий вызовы в список:

// test/InMemoryPayment.ts — второй адаптер, для тестов
class InMemoryPayment implements PaymentPort {
  public charged: { amountCents: number; key: string }[] = [];
  constructor(private decline = false) {}
  async charge(amountCents: number, key: string): Promise<ChargeResult> {
    this.charged.push({ amountCents, key });
    return this.decline
      ? { ok: false, reason: "card_declined" }
      : { ok: true, receiptId: "rcpt_test" };
  }
}

test("declined payment yields a declined order", async () => {
  const payments = new InMemoryPayment(true);
  const result = await new PlaceOrder(payments).run(makeOrder({ totalCents: 5000 }));
  expect(result.status).toBe("declined");
  expect(payments.charged).toHaveLength(1); // мы проверили побочный эффект без сети
});

Эти тесты выполняются за миллисекунды, детерминированно, без секретов. Тот же шов, что в проде позволяет заменить Stripe на Adyen, в тестах позволяет заменить его на фейк — тестовые дублёры — это просто ещё один адаптер. Это повседневный дивиденд от направления зависимостей внутрь, и это самое честное доказательство того, что граница реальна: если бы домен был приварен к Stripe, такого теста не могло бы существовать.