Command и Query: структура запросов и команд

Command и Query: структура запросов и команд

Command - меняет состояние. Query - не меняет. Это дисциплина: когда ты разделяешь их, код становится прозрачнее, тестируемее и предсказуемее.

Command меняет состояние и возвращает error; Query возвращает DTO без побочных эффектов

CQS vs CQRS

CQS (Command-Query Separation) - принцип Бертрана Мейера на уровне методов:

// CQS: метод либо возвращает данные, либо меняет состояние
type UserService struct { repo UserRepo }

// Command - меняет состояние, ничего не возвращает (кроме ошибки)
func (s *UserService) Deactivate(ctx context.Context, id int64) error {
    return s.repo.SetActive(ctx, id, false)
}

// Query - возвращает данные, ничего не меняет
func (s *UserService) GetByID(ctx context.Context, id int64) (User, error) {
    return s.repo.FindByID(ctx, id)
}
<?php
declare(strict_types=1);

// CQS: метод либо возвращает данные, либо меняет состояние
final class UserService
{
    public function __construct(
        private readonly UserRepository $repo,
    ) {}

    // Command - меняет состояние, ничего не возвращает
    public function deactivate(int $id): void
    {
        $this->repo->setActive($id, false);
    }

    // Query - возвращает данные, ничего не меняет
    public function getById(int $id): User
    {
        return $this->repo->findById($id);
    }
}
# CQS: метод либо возвращает данные, либо меняет состояние
class UserService:
    def __init__(self, repo: UserRepo) -> None:
        self._repo = repo

    # Command - меняет состояние, ничего не возвращает (ошибка - исключение)
    def deactivate(self, user_id: int) -> None:
        self._repo.set_active(user_id, False)

    # Query - возвращает данные, ничего не меняет
    def get_by_id(self, user_id: int) -> User:
        return self._repo.find_by_id(user_id)

CQRS поднимает CQS на архитектурный уровень - у команд и запросов разные модели, хендлеры, иногда разные хранилища.

Анатомия Command

Command - это DTO, описывающий намерение. Идея взята прямо из GoF: действие как объект отделяет намерение от исполнителя, поэтому команду можно сериализовать, положить в очередь, повторить или отменить:

// Command = что нужно сделать (imperative naming)
type CompleteLesson struct {
    UserID   int64 `json:"user_id" validate:"required"`
    LessonID int64 `json:"lesson_id" validate:"required"`
}

// Handler - выполняет команду
type CompleteLessonHandler struct {
    lessons  LessonRepo
    progress ProgressRepo
    events   EventPublisher
}

func (h *CompleteLessonHandler) Handle(ctx context.Context, cmd CompleteLesson) error {
    // 1. Валидация бизнес-правил
    lesson, err := h.lessons.GetByID(ctx, cmd.LessonID)
    if err != nil {
        return fmt.Errorf("lesson not found: %w", err)
    }

    if !lesson.IsAvailableFor(cmd.UserID) {
        return ErrLessonNotAvailable
    }

    // 2. Изменение состояния
    if err := h.progress.MarkCompleted(ctx, cmd.UserID, cmd.LessonID); err != nil {
        return fmt.Errorf("mark completed: %w", err)
    }

    // 3. Публикация события (опционально).
    // Внимание: запись в шаге 2 и Publish - две операции без общей транзакции (dual write).
    return h.events.Publish(ctx, LessonCompletedEvent{
        UserID:   cmd.UserID,
        LessonID: cmd.LessonID,
    })
}
<?php
declare(strict_types=1);

// Command = что нужно сделать (imperative naming)
final readonly class CompleteLesson
{
    public function __construct(
        public int $userId,
        public int $lessonId,
    ) {}
}

// Handler - выполняет команду
final class CompleteLessonHandler
{
    public function __construct(
        private readonly LessonRepository $lessons,
        private readonly ProgressRepository $progress,
        private readonly EventPublisher $events,
    ) {}

    public function __invoke(CompleteLesson $cmd): void
    {
        // 1. Валидация бизнес-правил
        $lesson = $this->lessons->getById($cmd->lessonId)
            ?? throw new LessonNotFoundException($cmd->lessonId);

        if (!$lesson->isAvailableFor($cmd->userId)) {
            throw new LessonNotAvailableException();
        }

        // 2. Изменение состояния
        $this->progress->markCompleted($cmd->userId, $cmd->lessonId);

        // 3. Публикация события (опционально)
        $this->events->publish(new LessonCompletedEvent(
            userId: $cmd->userId,
            lessonId: $cmd->lessonId,
        ));
    }
}

В Symfony такую команду диспатчат через MessageBusInterface::dispatch($cmd); обработчик помечается атрибутом #[AsMessageHandler].

from dataclasses import dataclass


# Command = что нужно сделать (imperative naming)
# Структурная валидация (required) - в __post_init__ или pydantic-моделью на границе
@dataclass(frozen=True, slots=True)
class CompleteLesson:
    user_id: int
    lesson_id: int


# Handler - выполняет команду
class CompleteLessonHandler:
    def __init__(
        self,
        lessons: LessonRepo,
        progress: ProgressRepo,
        events: EventPublisher,
    ) -> None:
        self._lessons = lessons
        self._progress = progress
        self._events = events

    def handle(self, cmd: CompleteLesson) -> None:
        # 1. Валидация бизнес-правил
        try:
            lesson = self._lessons.get_by_id(cmd.lesson_id)
        except LessonNotFoundError as e:
            raise CommandError("lesson not found") from e  # контекст сохраняется через «from»

        if not lesson.is_available_for(cmd.user_id):
            raise LessonNotAvailableError()

        # 2. Изменение состояния
        try:
            self._progress.mark_completed(cmd.user_id, cmd.lesson_id)
        except StorageError as e:
            raise CommandError("mark completed") from e

        # 3. Публикация события (опционально)
        self._events.publish(LessonCompletedEvent(
            user_id=cmd.user_id,
            lesson_id=cmd.lesson_id,
        ))

ℹ️ Command не возвращает данные

Command возвращает только error. Если после записи нужно показать результат - делай отдельный Query. Исключение: можно вернуть ID созданной сущности, но не более.

⚠️ Dual write: запись и публикация без общей транзакции

В примере выше запись прогресса и Publish - две независимые операции. Если Publish упадёт, прогресс уже сохранён, а событие потеряно; клиент повторит команду и получит повторную запись. В проде событие сохраняют в таблицу outbox в той же транзакции, что и прогресс, а публикует его отдельный процесс (подробнее - outbox и inbox).

Анатомия Query

Query - запрос данных без побочных эффектов:

// Query = что нужно прочитать
type GetTrackLessons struct {
    TrackID int64 `json:"track_id" validate:"required"`
    UserID  int64 `json:"user_id" validate:"required"`
}

// Результат - DTO под конкретный UI
type TrackLessonItem struct {
    ID          int64  `json:"id"`
    Title       string `json:"title"`
    Order       int    `json:"order"`
    Completed   bool   `json:"completed"`
    DurationMin int    `json:"duration_min"`
}

type GetTrackLessonsHandler struct {
    readRepo LessonReadRepo // отдельный репозиторий для чтения
}

func (h *GetTrackLessonsHandler) Handle(ctx context.Context, q GetTrackLessons) ([]TrackLessonItem, error) {
    return h.readRepo.ListByTrack(ctx, q.TrackID, q.UserID)
}
<?php
declare(strict_types=1);

// Query = что нужно прочитать
final readonly class GetTrackLessons
{
    public function __construct(
        public int $trackId,
        public int $userId,
    ) {}
}

// Результат - DTO под конкретный UI
final readonly class TrackLessonItem
{
    public function __construct(
        public int $id,
        public string $title,
        public int $order,
        public bool $completed,
        public int $durationMin,
    ) {}
}

final class GetTrackLessonsHandler
{
    public function __construct(
        // отдельный репозиторий для чтения
        private readonly LessonReadRepository $readRepo,
    ) {}

    /** @return TrackLessonItem[] */
    public function __invoke(GetTrackLessons $q): array
    {
        return $this->readRepo->listByTrack($q->trackId, $q->userId);
    }
}
from dataclasses import dataclass


# Query = что нужно прочитать
@dataclass(frozen=True, slots=True)
class GetTrackLessons:
    track_id: int
    user_id: int


# Результат - DTO под конкретный UI
@dataclass(frozen=True, slots=True)
class TrackLessonItem:
    id: int
    title: str
    order: int
    completed: bool
    duration_min: int


class GetTrackLessonsHandler:
    def __init__(self, read_repo: LessonReadRepo) -> None:
        self._read_repo = read_repo  # отдельный репозиторий для чтения

    def handle(self, q: GetTrackLessons) -> list[TrackLessonItem]:
        return self._read_repo.list_by_track(q.track_id, q.user_id)

⚠️ Query не должен делать запись

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

Валидация команд

Валидация разделяется на два уровня:

Уровень              Где                     Примеры
─────────────        ──────────────          ───────────────────────
Структурная          До хендлера             Поля не пустые, email валиден,
                     (middleware/validator)   числа в диапазоне

Бизнес-правила       В хендлере              Урок доступен пользователю,
                                             лимит не превышен,
                                             предыдущий шаг пройден
// Структурная валидация - можно вынести в middleware
func validateStruct(cmd any) error {
    return validator.New().Struct(cmd)
}

// Бизнес-валидация - только в хендлере, там есть контекст
func (h *CompleteLessonHandler) Handle(ctx context.Context, cmd CompleteLesson) error {
    // Бизнес-правило: предыдущие уроки должны быть пройдены
    prev, err := h.lessons.GetPrevious(ctx, cmd.LessonID)
    if err != nil {
        return err
    }
    if prev != nil {
        // IsCompleted ходит в БД, поэтому возвращает (bool, error):
        // ошибка хранилища - это не «урок не пройден»
        done, err := h.progress.IsCompleted(ctx, cmd.UserID, prev.ID)
        if err != nil {
            return fmt.Errorf("check previous: %w", err)
        }
        if !done {
            return ErrPreviousLessonNotCompleted
        }
    }
    // ...
}
<?php
declare(strict_types=1);

// Структурная валидация - атрибутами Symfony Validator на полях команды:
// final readonly class CompleteLesson {
//     public function __construct(
//         #[Assert\Positive] public int $userId,
//         #[Assert\Positive] public int $lessonId,
//     ) {}
// }

// Бизнес-валидация - только в хендлере, там есть контекст
final class CompleteLessonHandler
{
    public function __construct(
        private readonly LessonRepository $lessons,
        private readonly ProgressRepository $progress,
    ) {}

    public function __invoke(CompleteLesson $cmd): void
    {
        // Бизнес-правило: предыдущие уроки должны быть пройдены
        $prev = $this->lessons->getPrevious($cmd->lessonId);
        if ($prev !== null && !$this->progress->isCompleted($cmd->userId, $prev->id)) {
            throw new PreviousLessonNotCompletedException();
        }
        // ...
    }
}
from dataclasses import asdict


# Структурная валидация - можно вынести в middleware
# (в проде - pydantic: модель команды проверяет поля при создании)
def validate_struct(cmd: object) -> None:
    for name, value in asdict(cmd).items():
        if not value:
            raise ValueError(f"{name} is required")


# Бизнес-валидация - только в хендлере, там есть контекст
class CompleteLessonHandler:
    def __init__(self, lessons: LessonRepo, progress: ProgressRepo) -> None:
        self._lessons = lessons
        self._progress = progress

    def handle(self, cmd: CompleteLesson) -> None:
        # Бизнес-правило: предыдущие уроки должны быть пройдены
        prev = self._lessons.get_previous(cmd.lesson_id)  # Lesson | None
        if prev is not None and not self._progress.is_completed(cmd.user_id, prev.id):
            raise PreviousLessonNotCompletedError()
        # ...

Организация кода

Команды и запросы удобно группировать по фичам:

internal/
  lesson/
    command/
      complete_lesson.go      // Command + Handler
      start_lesson.go
    query/
      get_track_lessons.go    // Query + Handler
      get_lesson_detail.go
    domain/
      lesson.go               // доменная модель (Write)
      lesson_read.go           // DTO для чтения (Read)

Или проще, если проект небольшой - именно так разложен код в мини-проекте трека:

internal/
  usecase/
    complete_lesson.go        // Command
    get_track_lessons.go      // Query

Command Bus и Query Bus

В крупных проектах команды и запросы маршрутизируются через шину (bus):

// Простейший Command Bus
type HandlerFunc func(ctx context.Context, cmd any) error

type CommandBus struct {
    handlers map[reflect.Type]HandlerFunc
}

// Конструктор обязателен: запись в nil map вызовет panic
func NewCommandBus() *CommandBus {
    return &CommandBus{handlers: make(map[reflect.Type]HandlerFunc)}
}

func (b *CommandBus) Register(cmd any, handler HandlerFunc) {
    b.handlers[reflect.TypeOf(cmd)] = handler
}

func (b *CommandBus) Dispatch(ctx context.Context, cmd any) error {
    handler, ok := b.handlers[reflect.TypeOf(cmd)]
    if !ok {
        return fmt.Errorf("no handler for %T", cmd)
    }
    return handler(ctx, cmd)
}

// Регистрация: обёртка приводит any к конкретной команде
// bus.Register(CompleteLesson{}, func(ctx context.Context, c any) error {
//     return completeHandler.Handle(ctx, c.(CompleteLesson))
// })
<?php
declare(strict_types=1);

// Простейший Command Bus
final class CommandBus
{
    /** @var array<class-string, callable> */
    private array $handlers = [];

    public function register(string $commandClass, callable $handler): void
    {
        $this->handlers[$commandClass] = $handler;
    }

    public function dispatch(object $cmd): void
    {
        $class = $cmd::class;
        if (!isset($this->handlers[$class])) {
            throw new RuntimeException("no handler for $class");
        }
        ($this->handlers[$class])($cmd);
    }
}

В реальных Symfony-проектах руками такую шину не пишут - берут Symfony\Component\Messenger\MessageBusInterface с middleware-стеком (ValidationMiddleware, DoctrineTransactionMiddleware и собственный middleware для логирования).

from typing import Any, Callable


# Простейший Command Bus
class CommandBus:
    def __init__(self) -> None:
        self._handlers: dict[type, Callable[[Any], None]] = {}

    def register(self, cmd_type: type, handler: Callable[[Any], None]) -> None:
        self._handlers[cmd_type] = handler

    def dispatch(self, cmd: object) -> None:
        handler = self._handlers.get(type(cmd))
        if handler is None:
            raise LookupError(f"no handler for {type(cmd).__name__}")
        # вызываем handler(cmd) - у класса-хендлера это метод handle
        handler(cmd)

Для Go-проектов среднего размера Bus часто избыточен - достаточно прямого вызова хендлера. Bus пригодится, когда нужны middleware (логирование, метрики, retry) для всех команд разом.

Тестирование

Разделение Command/Query упрощает тесты:

func TestCompleteLesson_Success(t *testing.T) {
    // Arrange: мокаем только зависимости команды
    lessonRepo := &mockLessonRepo{lesson: testLesson}
    progressRepo := &mockProgressRepo{}
    handler := NewCompleteLessonHandler(lessonRepo, progressRepo, &mockPublisher{})

    // Act
    err := handler.Handle(ctx, CompleteLesson{UserID: 1, LessonID: 42})

    // Assert
    require.NoError(t, err)
    assert.True(t, progressRepo.completedCalled)
}

func TestCompleteLesson_PreviousNotCompleted(t *testing.T) {
    lessonRepo := &mockLessonRepo{lesson: testLesson, previous: prevLesson}
    progressRepo := &mockProgressRepo{completed: false}
    handler := NewCompleteLessonHandler(lessonRepo, progressRepo, &mockPublisher{})

    err := handler.Handle(ctx, CompleteLesson{UserID: 1, LessonID: 42})

    assert.ErrorIs(t, err, ErrPreviousLessonNotCompleted)
}
<?php
declare(strict_types=1);

final class CompleteLessonHandlerTest extends TestCase
{
    public function testSuccess(): void
    {
        // Arrange: мокаем только зависимости команды
        $lessons = $this->createMock(LessonRepository::class);
        $lessons->method('getById')->willReturn($this->testLesson());
        $progress = $this->createMock(ProgressRepository::class);
        $progress->expects(self::once())->method('markCompleted')->with(1, 42);

        $handler = new CompleteLessonHandler($lessons, $progress, new InMemoryEventPublisher());

        // Act
        $handler(new CompleteLesson(userId: 1, lessonId: 42));
    }

    public function testPreviousNotCompleted(): void
    {
        $lessons = $this->createMock(LessonRepository::class);
        $lessons->method('getPrevious')->willReturn($this->prevLesson());
        $progress = $this->createMock(ProgressRepository::class);
        $progress->method('isCompleted')->willReturn(false);

        $handler = new CompleteLessonHandler($lessons, $progress, new InMemoryEventPublisher());

        $this->expectException(PreviousLessonNotCompletedException::class);
        $handler(new CompleteLesson(userId: 1, lessonId: 42));
    }
}
# tests/test_complete_lesson.py (pytest; фейки руками, как в Go,
# альтернатива - unittest.mock.Mock)
def test_complete_lesson_success() -> None:
    # Arrange: мокаем только зависимости команды
    lesson_repo = FakeLessonRepo(lesson=test_lesson)
    progress_repo = FakeProgressRepo()
    handler = CompleteLessonHandler(lesson_repo, progress_repo, FakePublisher())

    # Act
    handler.handle(CompleteLesson(user_id=1, lesson_id=42))

    # Assert
    assert progress_repo.completed_called


def test_complete_lesson_previous_not_completed() -> None:
    lesson_repo = FakeLessonRepo(lesson=test_lesson, previous=prev_lesson)
    progress_repo = FakeProgressRepo(completed=False)
    handler = CompleteLessonHandler(lesson_repo, progress_repo, FakePublisher())

    with pytest.raises(PreviousLessonNotCompletedError):
        handler.handle(CompleteLesson(user_id=1, lesson_id=42))

Query тестировать ещё проще - нет побочных эффектов, только вход и выход.

Мини-задание

  • Выдели один use-case из своего проекта как Command (с Handler)
  • Выдели один экран как Query (с отдельной Read-структурой)
  • Напиши тест на Command: успешный сценарий + один бизнес-кейс с ошибкой
  • Проверь: ни один Query не делает запись в БД

Зарегистрируйтесь бесплатно, чтобы пройти квиз, вести прогресс.