Use Case: сценарии вместо «толстых сервисов»
Use Case: сценарии вместо «толстых сервисов»
Use-case - это один бизнес-сценарий. Не «UserService с 20 методами», а конкретное действие: «Завершить урок», «Зарегистрировать пользователя», «Создать заказ». Каждый use-case - отдельная структура с одним публичным методом.
В словаре DDD такой сценарий называется Application Service. Главное про него: он координирует шаги и не держит инвариантов - правил, верных для объекта в любом сценарии («урок нельзя завершить дважды»), их проверяет доменный объект. Решения, которые касаются только этого сценария (порядок шагов, что считать успехом, что делать, если не ушло письмо), принимает как раз use-case. Где проходит граница между этими видами правил, разобрано в уроке Domain Service vs Application Service.
Проблема: «толстый» сервис
В типичном Go-проекте появляется UserService с десятком методов:
// Так делать не стоит
type UserService struct {
db *sql.DB
mailer Mailer
cache Cache
logger *slog.Logger
}
func (s *UserService) Register(...) { ... }
func (s *UserService) Login(...) { ... }
func (s *UserService) ResetPassword(...) { ... }
func (s *UserService) UpdateProfile(...) { ... }
func (s *UserService) DeleteAccount(...) { ... }
func (s *UserService) GetStats(...) { ... }
<?php
// Так делать не стоит - все методы делят все зависимости
declare(strict_types=1);
namespace App\Application\Service;
use App\Application\Port\CachePort;
use App\Application\Port\MailerPort;
use App\Application\Port\UserRepositoryPort;
use Psr\Log\LoggerInterface;
final class UserService
{
public function __construct(
private readonly UserRepositoryPort $users,
private readonly MailerPort $mailer,
private readonly CachePort $cache,
private readonly LoggerInterface $logger,
) {}
public function register(/* ... */): void { /* ... */ }
public function login(/* ... */): void { /* ... */ }
public function resetPassword(/* ... */): void { /* ... */ }
public function updateProfile(/* ... */): void { /* ... */ }
public function deleteAccount(/* ... */): void { /* ... */ }
public function getStats(/* ... */): array { /* ... */ }
}
# Так делать не стоит
class UserService:
def __init__(
self,
conn: psycopg.Connection,
mailer: Mailer,
cache: Cache,
logger: logging.Logger,
) -> None:
self._conn = conn
self._mailer = mailer
self._cache = cache
self._logger = logger
def register(self, *args, **kwargs): ...
def login(self, *args, **kwargs): ...
def reset_password(self, *args, **kwargs): ...
def update_profile(self, *args, **kwargs): ...
def delete_account(self, *args, **kwargs): ...
def get_stats(self, *args, **kwargs): ...
Проблемы: все методы делят одни зависимости (хотя GetStats не нужен mailer), файл разрастается до 500+ строк, тестирование одного сценария требует мокать все зависимости.
Структура use-case
По форме use-case - это Command из GoF: один объект = одно действие, зависимости в конструкторе, вся работа в единственном методе. Именно поэтому use-case легко поставить в очередь, обернуть логами или транзакцией. Шаблон простой:
- Конструктор принимает порты (интерфейсы), которые нужны этому сценарию
- Input-структура описывает входные данные
- Output-структура описывает результат
- Метод Execute содержит оркестрацию: вызывает порты и доменные методы
// usecase/complete_lesson.go
package usecase
import (
"context"
"fmt"
"myapp/internal/domain"
"myapp/internal/usecase/ports"
)
type CompleteLessonInput struct {
UserID int64
LessonID int64
TrackID string
}
// Флага «запись новая» здесь нет: повторное завершение - доменная ошибка,
// значит при успехе урок всегда завершён впервые и такой флаг ничего не сообщал бы.
type CompleteLessonOutput struct {
Progress *domain.Progress
}
type CompleteLesson struct {
progressRepo ports.ProgressRepo
lessonRepo ports.LessonRepo
}
func NewCompleteLesson(pr ports.ProgressRepo, lr ports.LessonRepo) *CompleteLesson {
return &CompleteLesson{
progressRepo: pr,
lessonRepo: lr,
}
}
func (uc *CompleteLesson) Execute(ctx context.Context, in CompleteLessonInput) (*CompleteLessonOutput, error) {
// 1. Проверяем, существует ли урок
lesson, err := uc.lessonRepo.GetByID(ctx, in.LessonID)
if err != nil {
return nil, fmt.Errorf("get lesson: %w", err)
}
// 2. Получаем или создаём прогресс
progress, err := uc.progressRepo.GetOrCreate(ctx, in.UserID, in.LessonID)
if err != nil {
return nil, fmt.Errorf("get progress: %w", err)
}
// 3. Доменная логика - вызываем метод entity
if err := progress.Complete(lesson.TrackID); err != nil {
return nil, err // доменная ошибка
}
// 4. Сохраняем через порт
if err := uc.progressRepo.Save(ctx, progress); err != nil {
return nil, fmt.Errorf("save progress: %w", err)
}
return &CompleteLessonOutput{Progress: progress}, nil
}
<?php
// src/Application/UseCase/CompleteLessonUseCase.php
declare(strict_types=1);
namespace App\Application\UseCase;
use App\Application\Port\LessonRepositoryPort;
use App\Application\Port\ProgressRepositoryPort;
use App\Domain\Progress;
final readonly class CompleteLessonInput
{
public function __construct(
public int $userId,
public int $lessonId,
public string $trackId,
) {}
}
final class CompleteLessonOutput
{
public function __construct(
public readonly Progress $progress,
) {}
}
final class CompleteLessonUseCase
{
public function __construct(
private readonly ProgressRepositoryPort $progressRepo,
private readonly LessonRepositoryPort $lessonRepo,
) {}
public function execute(CompleteLessonInput $in): CompleteLessonOutput
{
// 1. Проверяем, существует ли урок
$lesson = $this->lessonRepo->getById($in->lessonId);
// 2. Получаем или создаём прогресс
$progress = $this->progressRepo->getOrCreate($in->userId, $in->lessonId);
// 3. Доменная логика - вызываем метод entity (бросит доменное исключение при нарушении правила)
$progress->complete($lesson->trackId());
// 4. Сохраняем через порт
$this->progressRepo->save($progress);
return new CompleteLessonOutput($progress);
}
}
# usecase/complete_lesson.py
from dataclasses import dataclass
from myapp.domain import Progress
from myapp.usecase.ports import LessonRepo, ProgressRepo
@dataclass(frozen=True, slots=True)
class CompleteLessonInput:
user_id: int
lesson_id: int
track_id: str
@dataclass(frozen=True, slots=True)
class CompleteLessonOutput:
progress: Progress
class CompleteLesson:
def __init__(self, progress_repo: ProgressRepo, lesson_repo: LessonRepo) -> None:
self._progress_repo = progress_repo
self._lesson_repo = lesson_repo
def execute(self, inp: CompleteLessonInput) -> CompleteLessonOutput:
# 1. Проверяем, существует ли урок (нет - адаптер бросит LessonNotFoundError)
lesson = self._lesson_repo.get_by_id(inp.lesson_id)
# 2. Получаем или создаём прогресс
progress = self._progress_repo.get_or_create(inp.user_id, inp.lesson_id)
# 3. Доменная логика - вызываем метод entity
# (нарушение правила - доменное исключение, пролетает наверх как есть)
progress.complete(lesson.track_id)
# 4. Сохраняем через порт
self._progress_repo.save(progress)
return CompleteLessonOutput(progress=progress)
ℹ️ Use-case оркестрирует, инварианты держит домен
Обрати внимание: use-case не проверяет, можно ли завершить урок повторно. Это делает доменный метод
progress.Complete(). Use-case вызывает порты в правильном порядке и передаёт данные между ними; в этом сценарии своих правил у него нет, но если бы были (например, «не удалось отправить письмо - урок всё равно завершён»), они жили бы именно здесь.
Правило «нельзя завершить урок дважды» называется инвариантом: его обязан держать сам доменный объект, иначе оно расползётся по сценариям и обойти его будет делом одной забытой строки. Как объект защищает свои инварианты и почему все изменения идут только через его методы - в уроке Aggregates и инварианты.
Input/Output вместо примитивов
Почему не передавать просто (userID, lessonID int64) в Execute?
// Плохо: при добавлении параметра меняется сигнатура
func (uc *CompleteLesson) Execute(ctx context.Context, userID, lessonID int64) error
// Плохо: легко перепутать два int64 местами
uc.Execute(ctx, lessonID, userID) // компилятор не поймает ошибку
// Хорошо: именованные поля, расширяемость
uc.Execute(ctx, CompleteLessonInput{
UserID: 42,
LessonID: 7,
})
<?php
// Плохо: позиционные аргументы легко перепутать
declare(strict_types=1);
$uc->execute(7, 42); // 42 - это userId или lessonId?
// Хорошо: именованные аргументы PHP 8.0+
$uc->execute(new CompleteLessonInput(
userId: 42,
lessonId: 7,
trackId: 'go',
));
// Альтернатива: named arguments на самом методе
final class CompleteLessonUseCase
{
public function execute(int $userId, int $lessonId, string $trackId): CompleteLessonOutput
{
// ...
}
}
// Вызывающий код безопасен от перестановки
$uc->execute(userId: 42, lessonId: 7, trackId: 'go');
# Плохо: при добавлении параметра меняется сигнатура
def execute(self, user_id: int, lesson_id: int) -> None: ...
# Плохо: легко перепутать два int местами
uc.execute(lesson_id, user_id) # ни интерпретатор, ни mypy не поймают ошибку
# Хорошо: именованные поля, расширяемость
uc.execute(CompleteLessonInput(
user_id=42,
lesson_id=7,
track_id="go",
))
# Альтернатива: keyword-only параметры - всё после «*» передаётся только по имени
def execute(self, *, user_id: int, lesson_id: int, track_id: str) -> CompleteLessonOutput: ...
# Вызывающий код защищён от перестановки
uc.execute(user_id=42, lesson_id=7, track_id="go")
Input-структура решает три задачи: именованные поля исключают путаницу, добавление нового поля не ломает вызывающий код, структуру удобно создавать в тестах.
При этом Input - не то же самое, что JSON-структура запроса. Тело запроса разбирает адаптер и сам перекладывает поля в Input, чтобы контракт API и контракт сценария могли меняться независимо друг от друга. Зачем нужны эти отдельные структуры и как между ними ходят данные - в уроке DTO и маппинг.
Обработка ошибок: доменные vs инфраструктурные
Use-case работает с двумя типами ошибок:
// Доменные ошибки - определены в пакете domain
var (
ErrLessonAlreadyCompleted = errors.New("lesson already completed")
ErrInvalidProgress = errors.New("invalid progress value")
)
// Инфраструктурные ошибки - приходят из адаптеров
// ошибки соединения, context.DeadlineExceeded и т.д.
// (sql.ErrNoRows сюда не доходит: адаптер переводит его в доменную ошибку)
<?php
// src/Domain/ProgressError.php - типизированные доменные исключения
declare(strict_types=1);
namespace App\Domain;
use DomainException;
final class ProgressError extends DomainException
{
public static function lessonAlreadyCompleted(): self
{
return new self('lesson already completed');
}
public static function invalidProgress(): self
{
return new self('invalid progress value');
}
}
// Инфраструктурные - из адаптеров: адаптер переводит Doctrine\DBAL\Exception
// в StorageException, объявленный рядом с портом
# domain/errors.py - доменные ошибки определены в пакете domain
class DomainError(Exception):
"""Общий предок: handler отличает доменные исключения по нему."""
class LessonAlreadyCompletedError(DomainError):
def __init__(self) -> None:
super().__init__("lesson already completed")
class InvalidProgressError(DomainError):
def __init__(self) -> None:
super().__init__("invalid progress value")
# Инфраструктурные ошибки - приходят из адаптеров
# psycopg.OperationalError, TimeoutError, и т.д.
Use-case оборачивает инфраструктурные ошибки для контекста, а доменные пробрасывает как есть:
func (uc *CompleteLesson) Execute(ctx context.Context, in CompleteLessonInput) (*CompleteLessonOutput, error) {
progress, err := uc.progressRepo.GetOrCreate(ctx, in.UserID, in.LessonID)
if err != nil {
// Инфраструктурная - оборачиваем
return nil, fmt.Errorf("complete lesson: get progress: %w", err)
}
if err := progress.Complete(in.TrackID); err != nil {
// Доменная - пробрасываем напрямую
return nil, err
}
// ...
}
<?php
declare(strict_types=1);
public function execute(CompleteLessonInput $in): CompleteLessonOutput
{
try {
$progress = $this->progressRepo->getOrCreate($in->userId, $in->lessonId);
} catch (StorageException $e) {
// Инфраструктурная - оборачиваем с контекстом через previous.
// StorageException объявлен рядом с портом (App\Application\Port):
// адаптер переводит в него Doctrine\DBAL\Exception, иначе use-case
// знал бы про драйвер базы. CompleteLessonException extends
// RuntimeException - своя ошибка сценария, как CompleteLessonError в Python
throw new CompleteLessonException('complete lesson: get progress', previous: $e);
}
// Доменные исключения - не ловим, пробрасываем
$progress->complete($in->trackId);
return new CompleteLessonOutput($progress);
}
class CompleteLessonError(Exception):
"""Сценарий «завершить урок» не выполнен по инфраструктурной причине."""
def execute(self, inp: CompleteLessonInput) -> CompleteLessonOutput:
try:
progress = self._progress_repo.get_or_create(inp.user_id, inp.lesson_id)
except StorageError as e:
# Инфраструктурная - оборачиваем в ошибку use-case с контекстом.
# Тип свой, а не RuntimeError: `from e` не аналог errors.Is, ловят
# по типу нового исключения. StorageError объявлен рядом с портом:
# адаптер переводит в него psycopg.Error, иначе use-case импортировал
# бы драйвер базы
raise CompleteLessonError("complete lesson: get progress") from e
# Доменная - не ловим, пролетает напрямую
progress.complete(inp.track_id)
# ...
Handler потом различает их для выбора HTTP-статуса. Полная таблица «доменная ошибка - код ответа» и правило держать этот маппинг в одной функции - в уроке HTTP адаптер:
if errors.Is(err, domain.ErrLessonAlreadyCompleted) {
// 409 Conflict
} else {
// 500 Internal Server Error
}
<?php
declare(strict_types=1);
try {
$uc->execute($input);
} catch (App\Domain\ProgressError $e) {
// Доменная - 409 Conflict / 400 Bad Request по типу
return new JsonResponse(['error' => $e->getMessage()], 409);
} catch (Throwable $e) {
// Инфраструктурная - 500, детали в лог, не в ответ
$logger->error('use-case failed', ['exception' => $e]);
return new JsonResponse(['error' => 'internal error'], 500);
}
try:
uc.execute(inp)
except LessonAlreadyCompletedError:
# 409 Conflict
...
except Exception:
# 500 Internal Server Error
...
⚠️ Не логируй в use-case
Логирование - инфраструктурная деталь. Use-case возвращает ошибку, а handler (или middleware) решает, как её залогировать. Это сохраняет use-case чистым и тестируемым.
Тестирование use-case
Главное преимущество: use-case тестируется без базы данных и HTTP. Подставить фейк вместо базы получается только потому, что конструктор принимает интерфейс, а не конкретный тип - механика описана в уроке Ports & Adapters. Как писать такие фейки и где вместо фейка нужен мок - в уроке Тестирование use-case без базы данных.
func TestCompleteLesson_Success(t *testing.T) {
// Arrange: фейковые адаптеры
progressRepo := inmemory.NewProgressRepo()
lessonRepo := inmemory.NewLessonRepo()
// Создаём тестовые данные
lessonRepo.Add(&domain.Lesson{ID: 1, TrackID: "go", Slug: "variables"})
progressRepo.Add(&domain.Progress{UserID: 42, LessonID: 1, Percent: 50})
uc := usecase.NewCompleteLesson(progressRepo, lessonRepo)
// Act
out, err := uc.Execute(context.Background(), usecase.CompleteLessonInput{
UserID: 42,
LessonID: 1,
})
// Assert
assert.NoError(t, err)
assert.True(t, out.Progress.IsCompleted())
}
func TestCompleteLesson_LessonNotFound(t *testing.T) {
progressRepo := inmemory.NewProgressRepo()
lessonRepo := inmemory.NewLessonRepo() // пустой - урока нет
uc := usecase.NewCompleteLesson(progressRepo, lessonRepo)
_, err := uc.Execute(context.Background(), usecase.CompleteLessonInput{
UserID: 42,
LessonID: 999,
})
assert.ErrorIs(t, err, domain.ErrLessonNotFound)
}
<?php
// tests/Application/UseCase/CompleteLessonUseCaseTest.php
declare(strict_types=1);
namespace App\Tests\Application\UseCase;
use App\Application\UseCase\CompleteLessonInput;
use App\Application\UseCase\CompleteLessonUseCase;
use App\Domain\Lesson;
use App\Domain\LessonError;
use App\Tests\Fakes\InMemoryLessonRepository;
use App\Tests\Fakes\InMemoryProgressRepository;
use PHPUnit\Framework\TestCase;
final class CompleteLessonUseCaseTest extends TestCase
{
public function testCompletesLessonSuccessfully(): void
{
$lessons = new InMemoryLessonRepository();
$progress = new InMemoryProgressRepository();
$lessons->add(new Lesson(id: 1, trackId: 'go', slug: 'variables'));
$uc = new CompleteLessonUseCase($progress, $lessons);
$out = $uc->execute(new CompleteLessonInput(userId: 42, lessonId: 1, trackId: 'go'));
self::assertTrue($out->progress->isCompleted());
}
public function testThrowsWhenLessonNotFound(): void
{
$uc = new CompleteLessonUseCase(
new InMemoryProgressRepository(),
new InMemoryLessonRepository(), // пустой
);
$this->expectException(LessonError::class);
$uc->execute(new CompleteLessonInput(userId: 42, lessonId: 999, trackId: 'go'));
}
}
# tests/test_complete_lesson.py (pytest)
def test_complete_lesson_success() -> None:
# Arrange: фейковые адаптеры
progress_repo = inmemory.ProgressRepo()
lesson_repo = inmemory.LessonRepo()
# Создаём тестовые данные
lesson_repo.add(Lesson(id=1, track_id="go", slug="variables"))
progress_repo.add(Progress(user_id=42, lesson_id=1, percent=50))
uc = usecase.CompleteLesson(progress_repo, lesson_repo)
# Act
out = uc.execute(usecase.CompleteLessonInput(user_id=42, lesson_id=1, track_id="go"))
# Assert
assert out.progress.is_completed()
def test_complete_lesson_lesson_not_found() -> None:
progress_repo = inmemory.ProgressRepo()
lesson_repo = inmemory.LessonRepo() # пустой - урока нет
uc = usecase.CompleteLesson(progress_repo, lesson_repo)
with pytest.raises(LessonNotFoundError):
uc.execute(usecase.CompleteLessonInput(user_id=42, lesson_id=999, track_id="go"))
Тесты запускаются за миллисекунды, не требуют Docker или тестовой базы, и проверяют именно бизнес-логику.
Один use-case = один файл
Простое правило организации кода:
usecase/
├── complete_lesson.go # CompleteLesson use-case
├── complete_lesson_test.go # тесты к нему
├── register_user.go # RegisterUser use-case
├── register_user_test.go
├── submit_quiz.go # SubmitQuiz use-case
└── submit_quiz_test.go
Каждый файл 50-100 строк. Легко найти, легко понять, легко протестировать.
🚫 Признак «толстого» use-case
Если
Executeзанимает больше 40-50 строк - скорее всего, часть логики должна уйти в доменный метод или в отдельный use-case. Use-case оркестрирует, а не вычисляет.
Мини-задание
- Возьми один метод из существующего «толстого» сервиса и вынеси его в отдельный use-case
- Определи Input и Output структуры для этого use-case
- Напиши метод
Execute(ctx context.Context, in Input) (*Output, error) - Напиши один happy-path тест с in-memory адаптером
- Напиши один тест на ошибку (например, entity не найден)