Главная › Use Case Pattern

Use Case Pattern

Use Case Pattern — слоистая архитектура Spring Boot + jOOQ: Controller → UseCase → Handler → Repository. Чёткие контракты, типобезопасность, тестируемость.

Статья внедрена в скилл AI-агента ucp-pattern-review / ucp-pattern-design Эталонная библиотека к статье usecase-pattern Use Case Pattern

Use Case Pattern — это методология, а не одна библиотека. У неё четыре составляющих:

  1. Сам паттерн. UseCase + Handler + Dispatcher — единый способ описывать бизнес-операции в коде.
  2. Спецификация. Универсальный шаблон того, что должно быть описано про сервис; хранится в git как код.
  3. Четыре уровня зрелости. Как паттерн и спецификация наращиваются по мере роста сервиса — от MVP до системы с десятками интеграций.
  4. Сквозной кейс. Бизнес-описание маркетплейса, на котором проверяется и сам паттерн, и спецификация, и уровни зрелости. Без него методология остаётся теорией.

Скиллы для AI-агентов работают со всеми четырьмя — это инструмент, а не отдельная составляющая.

1. Сам паттерн

Каждая бизнес-операция — отдельный UseCase и отдельный UseCaseHandler. Между входом (HTTP, очередь, cron) и выходом (БД, внешние API) проходит UseCaseDispatcher, который сводит их по типу.

вход (HTTP / очередь / расписание)
        ↓
Адаптер входа       ← переводит запрос в UseCase
        ↓
UseCaseDispatcher   ← находит обработчик по типу UseCase
        ↓
UseCaseHandler      ← бизнес-логика одной операции
        ↓
Адаптер выхода      ← хранилище, внешние сервисы

Главное:

  • Один UseCase — одна бизнес-операция. CreateOrder, ConfirmPayment, GetOrderById. Никаких «универсальных сервисов».
  • Контроллеры, обработчики очередей, cron — разные входные адаптеры к одному и тому же UseCase.
  • Слои не смешивают модели данных. Между ними — явный маппинг.

Готовая реализация паттерна — библиотека usecase-pattern.

2. Спецификация как код

В основе методологии лежит простое правило: спецификация — это код. Не Word-документ, не Confluence-страница, не PDF от аналитика. Markdown-файл в том же репозитории, что и код сервиса.

Что из этого следует:

  • Спека лежит в git рядом с кодом и проходит через PR-обзор как любой коммит.
  • История изменений видна в git log — кто, когда, почему изменил правило.
  • Формат структурирован: 16 разделов с заголовками, таблицами, списками. Это читают и люди, и инструменты — линтеры, генераторы кода, AI-агенты.
  • Контракты выводятся, а не дублируются: из раздела «Commands» получается OpenAPI, из «Domain Events» — AsyncAPI, из «Domain Model» — заготовки агрегатов.
  • Спека и код обязаны совпадать. Расхождение — баг, не «доработаем потом».

Шаблон поддерживает три уровня детализации (Tier), которые соответствуют уровням зрелости сервиса:

  • Tier A — legacy / слоёная архитектура. Минимальная спека: глоссарий, ER-схема, операции, правила, ошибки.
  • Tier B — UCP-сервис без или с CQRS. Добавляются UseCase-ы, Read Model.
  • Tier C — DDD / Hexagonal. Полные 16 разделов с агрегатами, событиями, сагами.

→ Use Case спецификация: универсальный шаблон + 9 гайдов по ролям (BA, архитектор, разработчик, QA, DevOps, security, дизайнер, сопровождение, AI-агент).

Спека → AI-агенты

Поскольку спецификация — это структурированный код, к ней применимы инструменты автоматизации. Для каждой статьи на сайте есть скилл Claude Code, который читает спеку и:

  • генерирует API-контракты из раздела «Commands» (/api-design);
  • генерирует агрегаты и события из «Domain Model» (/ddd-tactical-design);
  • генерирует UseCase + Handler из «Use Cases» (/usecase-pattern-design);
  • проверяет код по правилам спеки (/usecase-pattern-review, /ddd-tactical-review).

К статье с привязанным скиллом на сайте показывается жёлтый барсук. К статьям с эталонной библиотекой — зелёный. С эталонным примером проекта — синий. Все скиллы — в github.com/remodov/usecase-pattern-skills.

3. Четыре уровня зрелости

Методология — лестница. Каждый следующий уровень добавляет ответ на проблему, с которой предыдущий уже не справляется. Подняться можно когда есть причина, а не «потому что модно».

Уровень 1 — стартовый

Операции разнесены на отдельные UseCase-ы и обработчики; больше ничего. Один общий маршрут, одна модель данных. Когда брать: CRUD, тонкая бизнес-логика, MVP, внутренний инструмент. Когда уходить: когда чтение начинает мешать записи.

Уровень 2 — разделили чтение и запись

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

Уровень 3 — выделили домен

Появляется явная доменная модель — со своими понятиями (заказ, платёж, остаток), своими правилами и доменными событиями. Бизнес-логика живёт в домене, а не в обработчиках. Когда брать: сложные инварианты, важен язык, выделены границы (Bounded Context). Когда уходить: когда инфраструктура меняется чаще, чем сама бизнес-логика.

Уровень 4 — изолировали инфраструктуру

Бизнес-логика и инфраструктура (БД, шины, внешние API) разнесены жёстко через порты и адаптеры. Один и тот же UseCase можно вызвать из REST-эндпоинта, обработчика очереди и cron-задачи без дублирования. Когда брать: долгоживущий продукт, десятки интеграций, важна тестируемость и подменяемость.

Подсказка по выбору

Что в проектеУровень
CRUD, тонкая бизнес-логика, MVP1
Разная нагрузка на чтение и запись2
Сложные инварианты и доменный язык важны3
Много интеграций, важна изоляция логики от инфраструктуры4

В одном сервисе разные модули могут жить на разных уровнях: ядро бизнеса — на 4-м, справочники — на 1-м. Это нормально и часто выгоднее, чем «всё на 4-м для единообразия».

4. Сквозной кейс

Методология остаётся теорией, пока не приземлена на конкретный бизнес. Поэтому к ней прилагается сквозной кейс — маркетплейс: бизнес-описание в формате «как я понял задачу», без архитектурных терминов.

Кейс — равноправная часть методологии:

  • Стартовая точка для каждого нового сервиса. Перед спекой и кодом — текст про бизнес. Если бизнес не сформулирован, дальше идти бесполезно.
  • Эталон для скиллов. Бизнес-описание прогоняется через скиллы (/api-design, /ddd-tactical-design, /usecase-pattern-design), и из него генерируются API-контракты, агрегаты, UseCase-ы — мы видим, что методология работает.
  • Общая система координат для всех статей сайта. DDD, CQRS, Saga, Resilience4j, OAuth2 — всё разбирается на одном и том же кейсе. Не нужно каждый раз придумывать новый домен.

→ Кейс: маркетплейс — бизнес-описание (Tier A): стейкхолдеры, глоссарий, процессы, правила, ошибки, целевые объёмы.

Из этого текста через скиллы получаются артефакты по каждому сервису кейса (Customer BFF, Catalog, Order, Payment, Inventory, Notification) — они появятся в кейсе по мере наполнения.

Главные правила

Шесть принципов, общих для всех уровней зрелости. Технические подробности — в специализированных статьях по ссылкам.

  1. Один UseCase — одна бизнес-операция. Никаких «универсальных сервисов».
  2. Слои не смешивают модели данных. API-модель ≠ доменная модель ≠ модель хранения.
  3. Внешние зависимости — за интерфейсами. Платёжный шлюз, шина, отправка SMS — всё через порты.
  4. Одна бизнес-операция — одна транзакция. Всё или ничего.
  5. События публикуются атомарно с записью. Никаких «записал, а событие не дошло».
  6. Идемпотентность обязательна там, где она имеет смысл — платежи, создание заказов, повторные доставки сообщений.

Карта сайта

Каждый слой опирается на устоявшиеся практики. Сайт — методичный разбор каждой из них.

Controller / адаптер входа

UseCase + Handler (бизнес-логика)

Адаптер выхода / данные

Cross-cutting

Архитектура и проектирование

Спецификация и команда

Дальше