Command: действия как объекты (и почему это удобно)

Command: действия как объекты (и почему это удобно)

«Действие как объект» звучит странно - пока не дойдёшь до очередей, отмены и логов аудита. Тогда Command становится очевидным.

Проблема

В админке есть несколько действий: переиндексация, рассылка, экспорт данных. Обработчик:

func HandleAdmin(action string) error {
    switch action {
    case "reindex":
        // 20 строк логики
    case "newsletter":
        // 30 строк логики
    case "export":
        // 25 строк логики
    default:
        return fmt.Errorf("unknown action: %s", action)
    }
    return nil
}
<?php
declare(strict_types=1);

function handleAdmin(string $action): void
{
    match ($action) {
        'reindex'    => /* 20 строк логики */ null,
        'newsletter' => /* 30 строк логики */ null,
        'export'     => /* 25 строк логики */ null,
        default      => throw new InvalidArgumentException("unknown action: $action"),
    };
}
def handle_admin(action: str) -> None:
    match action:
        case "reindex":
            pass  # 20 строк логики
        case "newsletter":
            pass  # 30 строк логики
        case "export":
            pass  # 25 строк логики
        case _:
            raise ValueError(f"unknown action: {action}")

Проблемы: один разрастающийся switch/match (нарушение OCP), нельзя ставить действия в очередь, нельзя откатить, нельзя логировать единообразно.

Решение: Command

Command - это действие, оформленное как объект. Вместо «вызвать функцию с параметрами» - создать структуру с методом Execute(). Это позволяет:

  • ставить в очередь
  • логировать единообразно
  • повторять (retry)
  • откатывать (undo)
  • сериализовать и выполнять позже

Producer → Queue → Invoker, выполненные команды попадают в History, откуда их откатывают через Undo

Команды для админки

type Command interface {
    Execute() error
}

type ReindexCommand struct {
    indexName string
}

func (c ReindexCommand) Execute() error {
    log.Printf("reindexing %s...", c.indexName)
    // логика переиндексации
    return nil
}

type SendNewsletterCommand struct {
    templateID string
    recipients []string
}

func (c SendNewsletterCommand) Execute() error {
    log.Printf("sending newsletter %s to %d recipients",
        c.templateID, len(c.recipients))
    // логика рассылки
    return nil
}

Диспетчер выполняет любую команду:

func RunCommand(cmd Command) error {
    log.Printf("executing: %T", cmd)
    start := time.Now()
    err := cmd.Execute()
    log.Printf("done: %T, duration=%v, err=%v",
        cmd, time.Since(start), err)
    return err
}
interface Command
{
    public function execute(): void;
}

final class ReindexCommand implements Command
{
    public function __construct(
        private readonly string $indexName,
    ) {}

    public function execute(): void
    {
        // логика переиндексации
    }
}

final class SendNewsletterCommand implements Command
{
    public function __construct(
        private readonly string $templateId,
        private readonly array $recipients,
    ) {}

    public function execute(): void
    {
        // логика рассылки
    }
}

Диспетчер выполняет любую команду:

final class CommandRunner
{
    public function __construct(
        private readonly LoggerInterface $logger,
    ) {}

    public function run(Command $cmd): void
    {
        $name = $cmd::class;
        $this->logger->info("executing: $name");
        $t = microtime(true);
        try {
            $cmd->execute();
        } finally {
            $ms = (int) ((microtime(true) - $t) * 1000);
            $this->logger->info("done: $name, duration_ms=$ms");
        }
    }
}

В Symfony такой паттерн - основа Messenger: команда (Message) идёт через MessageBus, который сам логирует/ретраит/кладёт в очередь.

import logging
import time
from dataclasses import dataclass
from typing import Protocol

logger = logging.getLogger(__name__)


class Command(Protocol):
    def execute(self) -> None: ...


@dataclass(slots=True)
class ReindexCommand:
    index_name: str

    def execute(self) -> None:
        logger.info("reindexing %s...", self.index_name)
        # логика переиндексации


@dataclass(slots=True)
class SendNewsletterCommand:
    template_id: str
    recipients: list[str]

    def execute(self) -> None:
        logger.info("sending newsletter %s to %d recipients", self.template_id, len(self.recipients))
        # логика рассылки

Диспетчер выполняет любую команду:

def run_command(cmd: Command) -> None:
    name = type(cmd).__name__
    logger.info("executing: %s", name)
    start = time.perf_counter()
    try:
        cmd.execute()
    finally:
        logger.info("done: %s, duration_ms=%d", name, (time.perf_counter() - start) * 1000)


run_command(ReindexCommand("users"))

Celery и RQ - аналог Symfony Messenger: задача сериализуется и кладётся в Redis/RabbitMQ, воркер выполняет её позже. Команда там - функция с декоратором @app.task плюс её аргументы.

Command Queue: очередь задач

Команды можно складывать в очередь и выполнять последовательно:

type CommandQueue struct {
    queue []Command
    mu    sync.Mutex
}

func (q *CommandQueue) Add(cmd Command) {
    q.mu.Lock()
    defer q.mu.Unlock()
    q.queue = append(q.queue, cmd)
}

func (q *CommandQueue) ExecuteAll() error {
    q.mu.Lock()
    cmds := q.queue
    q.queue = nil
    q.mu.Unlock()

    for _, cmd := range cmds {
        if err := cmd.Execute(); err != nil {
            return fmt.Errorf("command %T failed: %w", cmd, err)
        }
    }
    return nil
}
<?php
declare(strict_types=1);

final class CommandQueue
{
    /** @var list<Command> */
    private array $queue = [];

    public function add(Command $cmd): void
    {
        $this->queue[] = $cmd;
    }

    public function executeAll(): void
    {
        $cmds = $this->queue;
        $this->queue = [];

        foreach ($cmds as $cmd) {
            try {
                $cmd->execute();
            } catch (Throwable $e) {
                throw new RuntimeException(
                    sprintf('command %s failed: %s', $cmd::class, $e->getMessage()),
                    previous: $e,
                );
            }
        }
    }
}
import threading


class CommandFailedError(Exception):
    """Команда из очереди упала; какая именно - в атрибуте command."""

    def __init__(self, command: Command) -> None:
        super().__init__(f"command {type(command).__name__} failed")
        self.command = command


class CommandQueue:
    def __init__(self) -> None:
        self._queue: list[Command] = []
        self._lock = threading.Lock()

    def add(self, cmd: Command) -> None:
        with self._lock:
            self._queue.append(cmd)

    def execute_all(self) -> None:
        with self._lock:
            cmds, self._queue = self._queue, []

        for cmd in cmds:
            try:
                cmd.execute()
            except Exception as e:
                # Своё исключение с командой внутри, а не RuntimeError: воркер
                # ловит except CommandFailedError и знает, что повторить.
                # `from e` - не аналог errors.Is: ловят по типу нового
                # исключения, исходное - в __cause__
                raise CommandFailedError(cmd) from e

Это основа для background jobs: сериализуешь команду (JSON), кладёшь в Redis/PostgreSQL, воркер десериализует и выполняет.

ℹ️ Команда = удобно для очередей

Ты можешь сериализовать команду (или её данные) и выполнить позже - почти готовый background job. Laravel Queues / Symfony Messenger (PHP), asynq или river (Go) - все построены на этой идее.

Undo/Redo: откат команд

Если команда знает, как себя отменить, получается Undo. Для этого команда хранит всё, что нужно для отмены, и есть два способа:

  • Запомнить прежнее значение перед изменением и вернуть его в Undo. Подходит, когда команда целиком перезаписывает значение: старый email, старая цена. Так сделан пример ниже.
  • Выполнить обратную операцию: пополнение на 100 отменяется списанием 100, добавление элемента - его удалением. Подходит, когда действие - приращение, а значение между Execute и Undo могли поменять другие. Если в таком случае восстановить снимок «до», вместе со своим действием откатятся и чужие изменения.
type UndoableCommand interface {
    Execute() error
    Undo() error
}

type ChangeEmailCommand struct {
    userRepo UserRepo
    userID   int64
    oldEmail string
    newEmail string
    executed bool
}

func (c *ChangeEmailCommand) Execute() error {
    user, err := c.userRepo.Get(c.userID)
    if err != nil {
        return fmt.Errorf("get user: %w", err)
    }
    c.oldEmail = user.Email // запоминаем для Undo
    if err := c.userRepo.UpdateEmail(c.userID, c.newEmail); err != nil {
        return err
    }
    c.executed = true
    return nil
}

func (c *ChangeEmailCommand) Undo() error {
    if !c.executed {
        return errors.New("command was not executed")
    }
    return c.userRepo.UpdateEmail(c.userID, c.oldEmail)
}
<?php
declare(strict_types=1);

interface UndoableCommand
{
    public function execute(): void;

    public function undo(): void;
}

final class ChangeEmailCommand implements UndoableCommand
{
    private ?string $oldEmail = null;

    public function __construct(
        private readonly UserRepository $userRepo,
        private readonly int $userId,
        private readonly string $newEmail,
    ) {}

    public function execute(): void
    {
        $user = $this->userRepo->get($this->userId);
        $this->oldEmail = $user->email; // запоминаем для Undo
        $this->userRepo->updateEmail($this->userId, $this->newEmail);
    }

    public function undo(): void
    {
        if ($this->oldEmail === null) {
            throw new LogicException('command was not executed');
        }
        $this->userRepo->updateEmail($this->userId, $this->oldEmail);
    }
}
from typing import Protocol


class UndoableCommand(Protocol):
    def execute(self) -> None: ...
    def undo(self) -> None: ...


class ChangeEmailCommand:
    def __init__(self, user_repo: UserRepo, user_id: int, new_email: str) -> None:
        self._user_repo = user_repo
        self._user_id = user_id
        self._new_email = new_email
        self._old_email: str | None = None

    def execute(self) -> None:
        user = self._user_repo.get(self._user_id)
        self._old_email = user.email  # запоминаем для Undo
        self._user_repo.update_email(self._user_id, self._new_email)

    def undo(self) -> None:
        if self._old_email is None:
            raise RuntimeError("command was not executed")
        self._user_repo.update_email(self._user_id, self._old_email)

Менеджер хранит историю и может откатить:

type History struct {
    done []UndoableCommand
}

func (h *History) Execute(cmd UndoableCommand) error {
    if err := cmd.Execute(); err != nil {
        return err
    }
    h.done = append(h.done, cmd)
    return nil
}

func (h *History) Undo() error {
    if len(h.done) == 0 {
        return fmt.Errorf("nothing to undo")
    }
    last := h.done[len(h.done)-1]
    h.done = h.done[:len(h.done)-1]
    return last.Undo()
}
<?php
declare(strict_types=1);

final class History
{
    /** @var list<UndoableCommand> */
    private array $done = [];

    public function execute(UndoableCommand $cmd): void
    {
        $cmd->execute();
        $this->done[] = $cmd;
    }

    public function undo(): void
    {
        $last = array_pop($this->done);
        if ($last === null) {
            throw new RuntimeException('nothing to undo');
        }
        $last->undo();
    }
}
class History:
    def __init__(self) -> None:
        self._done: list[UndoableCommand] = []

    def execute(self, cmd: UndoableCommand) -> None:
        cmd.execute()
        self._done.append(cmd)

    def undo(self) -> None:
        if not self._done:
            raise RuntimeError("nothing to undo")
        last = self._done.pop()
        last.undo()

Правило выбора: Undo должен откатывать ровно своё действие. Перезапись - возвращай прежнее значение; приращение - применяй обратную операцию.

Command в CLI-приложениях

Каждая субкоманда CLI - это Command:

// cobra-стиль
type CLICommand struct {
    Name string
    Run  func(args []string) error
}

commands := []CLICommand{
    {Name: "migrate", Run: runMigrations},
    {Name: "seed", Run: runSeeds},
    {Name: "serve", Run: startServer},
}
<?php
declare(strict_types=1);

// Symfony Console-стиль
abstract class CLICommand
{
    abstract public function name(): string;

    /** @param list<string> $args */
    abstract public function run(array $args): int;
}

final class MigrateCommand extends CLICommand
{
    public function name(): string
    {
        return 'migrate';
    }

    public function run(array $args): int
    {
        // запуск миграций
        return 0;
    }
}

$commands = [
    new MigrateCommand(),
    new SeedCommand(),
    new ServeCommand(),
];
from dataclasses import dataclass
from typing import Callable


# click/argparse-стиль
@dataclass(frozen=True, slots=True)
class CLICommand:
    name: str
    run: Callable[[list[str]], None]


commands = [
    CLICommand(name="migrate", run=run_migrations),
    CLICommand(name="seed", run=run_seeds),
    CLICommand(name="serve", run=start_server),
]

Библиотеки cobra и urfave/cli (Go), Symfony Console (PHP), click (Python) построены на этом паттерне: каждая команда - объект с именем, описанием и функцией выполнения.

Связь Command и CQRS

CQRS (Command Query Responsibility Segregation) разделяет модель записи и модель чтения. Слово «команда» там означает намерение изменить состояние - сообщение с данными, которое обрабатывает свой handler:

Command (запись)Query (чтение)
CreateUserCommandGetUserQuery
ChangeEmailCommandListUsersQuery
DeleteOrderCommandGetOrderStatsQuery
Меняют состояниеТолько читают
Могут быть в очередиОбычно синхронные
Валидация + бизнес-правилаПростые SELECT-ы

⚠️ Одно слово, два разных понятия

Совпадение имени сбивает с толку, и на собеседовании это слышно сразу. Разница такая:

GoF CommandКоманда в CQRS
Что этоповеденческий паттерн: запрос упакован в объект с методом вроде Execute()сообщение о намерении изменить состояние
Зачемотложить, поставить в очередь, залогировать, отменить (Undo)разделить путь записи и путь чтения
Обязателен ли метод исполнения у самого объектада, в этом суть паттернанет: команда - обычно структура с данными, исполняет её отдельный handler
Undoтипичная часть паттернане подразумевается; откат - это компенсация или новая команда

CQRS не требует паттерна GoF Command. Требование у него одно: путь записи и путь чтения разделены. Как именно оформлена команда - объектом с Execute(), структурой плюс handler или просто вызовом метода сервиса - дело реализации.

Общее у них действительно есть: и там, и там действие представлено отдельным объектом, а не набором аргументов. Дальше сходство заканчивается.

⚠️ Command ≠ обработчик запроса

Не оборачивай каждый HTTP-handler в Command. Command полезен когда действие нужно ставить в очередь, логировать, повторять или откатывать. Простой CRUD-обработчик не нуждается в Command.

Когда НЕ использовать

Простые действия - если действие это один вызов функции без необходимости очередей, retry или undo, Command - лишний слой.

Нет очереди и отката - если ты не планируешь ставить команды в очередь или откатывать, обычная функция проще.

Overengineering - Command ради Command (один тип команды, один обработчик) добавляет сложности без пользы.

Связь с другими паттернами

Command + Observer - команда публикует событие после выполнения
Command + Memento - Memento сохраняет состояние для Undo
Command + Factory - фабрика создаёт нужную команду по параметрам
Command + Queue - команды в очереди = background jobs

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

  • Сделай 2-3 команды с интерфейсом Execute() error и диспетчер, который выполняет их
  • Реализуй Undo: команда запоминает состояние «до» и умеет откатиться
  • Сделай CommandQueue - складывай команды и выполняй пакетно
  • Посмотри исходники cobra - как устроена структура Command

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