Идемпотентность: где уместно, а где - нет

Многие используют идемпотентность, даже не задумываясь об этом. И не всегда это использование делает код и приложение лучше. Давайте разберемся.

Первое, что нужно помнить: идемпотентность - это свойство операции. Это важно, потому что, когда мы проектируем систему или смотрим на код, мы можем смотреть через разные призмы.

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

🍀 Доменными сущностями с бизнес-логикой,
🍀 Сервисами с технической логикой,
🍀 Application-командами (каждая команда, по сути, является операцией),
🍀 Репозиториями,
🍀 API эндпоинты, которые мы предоставляем и вызываем - это тоже операции.

Список, разумеется, далеко не полный.

Если операции - один из основных способов думать о системе и коде, то идемпотентность - один из способов мыслить об операциях.

🗒 Идемпотентная операция дает один и тот же результат (не меняет состояние системы) при повторных вызовах с теми же аргументами.

Давайте рассмотрим три варианта одной и той же операции.

public function giveBonus(Order $order, Account $account): void
{
    $amount = $this->bonusStrategy->calculate($order);
    $account->accrue($amount);
}

public function giveBonus(Order $order, Account $account): void
{
    if ($account->orderRewarded($order)) {
        throw new \DomainException('Бонусы за этот заказ начислены');
    }

    $amount = $this->bonusStrategy->calculate($order);
    $account->accrue($amount);
}

public function giveBonus(Order $order, Account $account): void
{
    if ($account->orderRewarded($order)) {
        return;
    }

    $amount = $this->bonusStrategy->calculate($order);
    $account->accrue($amount);
}

Идемпотентным является только последний пример. При повторных вызовах с одинаковыми order и $account состояние системы не изменится. Бонусы начислятся только однажды.

Второй пример, где бросается исключение, не является идемпотентным, поскольку повторный вызов операции с теми же аргументами запрещен.

Первый пример является просто ошибочным. Едва ли есть хоть одна система, где разрешено бесконечное начисление бонусов за один и тот же заказ.

Так вот, правило, которого придерживаюсь лично я, звучит так:

Чем на более глубоком слое предоставляется операция, тем менее желательна идемпотентность.

А именно:

🍀 В доменном слое - никогда.
🍀 В Application слое - крайне редко и строго осознанно.
🍀 В контроллерах - сколько угодно по потребности, но тоже осознанно.

Доменный слой - не место для замалчивания ошибок. Я недавно написал целую серию постов о том, почему важна строгость кода (первый пост).

В Application слое каждая команда является по сути отдельной операцией. И вот здесь часто кроется соблазн сделать такую операцию идемпотентной в угоду сиюминутной потребности.

Чтобы принять окончательное решение, вам нужно ответить себе на вопрос, возможны ли кейсы, при которых вас не устроит молчаливое отрабатывание повторных нежелательных вызовов.

Если сомневаетесь, то можно поступить следующим образом: сделать команду неидемпотентной и написать еще одну команду-обертку, которая будет делать идемпотентный вызов исходной команды. При этом желательно подчеркнуть идемпотентность новой команды в ее названии.

Например, команду RewardForOrder вы вызываете по нажатию кнопки в интерфейсе. А команду RewardForOrderIdempotent вы вызываете при массовой автоматической раздаче бонусов по крону. Очевидно, что в первом случае вы хотите заявить об ошибке, а во втором - промолчать.

Таким образом, идемпотентность должна использоваться вами осознанно и только для того, чтобы сделать работу системы предсказуемой и безопасной, и никогда для того, чтобы сделать разработку удобнее и быстрее.