Use cases и interactors

Кольцо Use Cases и что ему принадлежит

В кольцевой модели Clean Architecture кольцо Use Cases находится непосредственно снаружи кольца Entities. Оно содержит бизнес-правила, специфичные для приложения — правила, выражающие, что именно это приложение делает с entities.

Различие важно. Entity содержит общеприкладные бизнес-правила: у Order должна быть хотя бы одна позиция перед подтверждением; итог Invoice должен равняться сумме позиций. Эти правила верны в любом приложении, построенном на этом бизнесе. Use case содержит прикладные правила: чтобы сгенерировать счёт, сначала проверить, что заказ подтверждён, затем проверить billing holds, затем создать entity Invoice, затем опубликовать событие. Эти шаги специфичны для процесса данного приложения.

Кольцу Use Cases принадлежит:

• Один класс на use case (interactor)
• Интерфейс input port (что принимает use case)
• Интерфейс output port (что производит use case)
• Request model (структура данных, поступающая внутрь)
• Response model (структура данных, выходящая наружу)

Паттерн interactor

Interactor — класс, реализующий один use case. Он содержит шаги прикладной логики этого use case и ничего больше. Он не знает об HTTP, SQL, JSON или любой концепции фреймворка.

// Все типы здесь — в кольце Use Cases, без импортов фреймворка
interface GenerateInvoiceInputPort {
  execute(request: GenerateInvoiceRequest): Promise<void>;
}

interface GenerateInvoiceOutputPort {
  presentSuccess(response: GenerateInvoiceResponse): void;
  presentError(error: InvoiceGenerationError): void;
}

class GenerateInvoiceInteractor implements GenerateInvoiceInputPort {
  constructor(
    private readonly orders: IOrderRepository,
    private readonly invoices: IInvoiceRepository,
    private readonly billingHolds: IBillingHoldChecker,
    private readonly presenter: GenerateInvoiceOutputPort,
  ) {}

  async execute(request: GenerateInvoiceRequest): Promise<void> {
    const order = await this.orders.findById(request.orderId);
    if (!order) {
      this.presenter.presentError(new InvoiceGenerationError('ORDER_NOT_FOUND'));
      return;
    }
    if (order.status !== OrderStatus.Confirmed) {
      this.presenter.presentError(new InvoiceGenerationError('ORDER_NOT_CONFIRMED'));
      return;
    }
    const hold = await this.billingHolds.checkForHold(order.customerId);
    if (hold.active) {
      this.presenter.presentError(new InvoiceGenerationError('BILLING_HOLD_ACTIVE'));
      return;
    }
    const invoice = Invoice.createFor(order);
    await this.invoices.save(invoice);
    this.presenter.presentSuccess(new GenerateInvoiceResponse(invoice.id, invoice.total));
  }
}

GenerateInvoiceInteractor — единственное каноническое место, говорящее: «вот что значит сгенерировать счёт». Каждый вызывающий — HTTP-контроллер, batch-задание, CLI, обработчик вебхука — вызывает этот interactor. Ни один вызывающий не может пропустить проверку billing hold, потому что она внутри interactor, а не в вызывающем.

Request models и response models — зачем они нужны

Распространённый ранний shortcut — передавать объект HTTP-запроса прямо в use case:

// Неверно: кольцо Use Cases импортирует тип фреймворка
async execute(req: ExpressRequest): Promise<ExpressResponse>

Это создаёт source-code зависимость от HTTP-фреймворка в кольце Use Cases — зависимость, указывающую наружу, что нарушает концентрическое правило. Хуже того, use case становится нетестируемым без реального объекта HTTP-запроса.

Исправление — request models и response models: простые структуры данных, определённые в кольце Use Cases, несущие именно те данные, которые нужны use case, в domain-терминах.

// Верно: кольцо Use Cases определяет собственные формы данных
class GenerateInvoiceRequest {
  constructor(
    public readonly orderId: OrderId,
    public readonly requestedBy: UserId,
  ) {}
}

class GenerateInvoiceResponse {
  constructor(
    public readonly invoiceId: InvoiceId,
    public readonly total: Money,
    public readonly generatedAt: Date,
  ) {}
}

HTTP-контроллер (в Interface Adapters) парсит HTTP-запрос и конструирует GenerateInvoiceRequest. Interactor никогда не видит ExpressRequest. Interactor производит GenerateInvoiceResponse. HTTP-presenter (тоже в Interface Adapters) конвертирует его в JSON HTTP-ответ. Перевод между типами фреймворка и типами use case — это полная работа кольца Interface Adapters.

Input ports и output ports

Interactor взаимодействует через два интерфейса портов, оба определённых в кольце Use Cases:

Input port (GenerateInvoiceInputPort): интерфейс, который реализует interactor. Вызывающие (HTTP-контроллеры, CLI-адаптеры, batch-задания) импортируют этот интерфейс и вызывают execute. Они никогда не импортируют конкретный класс interactor. Это значит, что всю реализацию interactor можно заменить или замокировать в тестах без изменений в вызывающих.

Output port (GenerateInvoiceOutputPort): интерфейс, который interactor вызывает для доставки результатов. Interactor не возвращает значение — он вызывает output port, который реализует кольцо Interface Adapters (как presenter). Это инверсия зависимостей, применённая к стороне ответа: interactor не знает о HTTP-статус-кодах, JSON-сериализации или стриминге — он вызывает метод на domain-языке вроде presentSuccess(response) и позволяет presenter решить, как его отрендерить.

Эта двухпортовая структура отражает primary и secondary ports hexagonal architecture, теперь применённую конкретно на границе кольца Use Cases.