Idempotency: как не выполнить одно и то же дважды
Idempotency: как не выполнить одно и то же дважды
В мире событий доставка работает по принципу at-least-once: брокер гарантирует, что сообщение дойдёт хотя бы один раз, но может доставить его дважды, трижды или десять раз. Сеть моргнула, consumer перезапустился, offset не закоммитился - и событие приходит повторно. Если обработчик не готов к этому, пользователь получит два списания, две ачивки или два письма.
Idempotency - это свойство операции: повторный вызов с теми же входными
данными не меняет результат. f(x) = f(f(x)). Для event-driven архитектуры
это не оптимизация и не nice-to-have, а обязательное требование к каждому
подписчику.
⚠️ Идемпотентная операция и дедуплицированная обработка - разные вещи
Их постоянно смешивают, в том числе в статьях: «поставил inbox-таблицу - обработчик стал идемпотентным». Это неверно, и различие практическое.
Идемпотентная операция безопасна к повтору сама по себе, без внешней памяти:
-- идемпотентно: сколько раз ни выполни, состояние одно UPDATE users SET status = 'active' WHERE id = 42; INSERT INTO badges (user_id, badge) VALUES (42, 'first-lesson') ON CONFLICT (user_id, badge) DO NOTHING;Неидемпотентная операция остаётся неидемпотентной, что бы ни лежало рядом:
-- не идемпотентно: каждый вызов меняет результат UPDATE users SET balance = balance + 100 WHERE id = 42;Inbox-таблица не превращает вторую операцию в первую. Она делает другое: дедуплицирует обработку - гарантирует, что по конкретной паре
(event_id, handler)тело обработчика выполнится один раз согласно записи в нашей базе. Это протокол вокруг операции, а не свойство операции.Почему различие важно на практике:
- дедупликация работает только там, где есть её запись. Потеряли inbox (восстановили базу из бэкапа, сменили ключ дедупа, поменяли имя handler-а) - и защита исчезла. Идемпотентная операция переживает всё это без последствий;
- дедупликация не помогает против повторов вне канала. Оператор дёрнул тот же endpoint руками, retry прошёл под другим
event_id, событие пересобрали при миграции - для inbox это новое событие;- дедупликация ничего не говорит про частичное применение. Если внутри обработчика два внешних вызова, а между ними сбой, запись в inbox либо откатится вместе с ними (тогда всё хорошо), либо нет - и тогда «уже обработано» соврёт.
Поэтому порядок предпочтений такой: сначала сделать операцию идемпотентной по природе (UPSERT вместо инкремента, целевое состояние вместо дельты, ключ операции на стороне внешнего API), и только для того, что так переписать нельзя, добавлять дедупликацию через inbox.
Почему at-least-once - это норма
End-to-end exactly-once для произвольных внешних эффектов нельзя получить одной транспортной гарантией: подтверждение может потеряться уже после обработки (Two Generals' Problem), и брокер пришлёт сообщение снова. Kafka даёт exactly-once в границах своей транзакции - топик → топик вместе с коммитом offset (разбор); RabbitMQ такого механизма не даёт, а NATS JetStream даёт похожую гарантию (дедупликация публикаций по заголовку Nats-Msg-Id плюс двойной ack) тоже только внутри брокера. Но за пределами брокера - запись в базу, письмо, чужой API - гарантия заканчивается: там «ровно один раз» обеспечивает идемпотентная обработка на уровне приложения. И требование это шире, чем подписчики: шаги и компенсации саги повторяются при retry по тем же причинам, поэтому каждый шаг тоже обязан выдерживать повторный вызов.
Ситуации, когда событие приходит повторно:
- Consumer упал после обработки, но до коммита offset
- Сетевой таймаут между consumer и брокером
- Rebalancing партиций в Kafka
- Ручной replay событий при инциденте
Idempotency Key: event ID как натуральный ключ
Каждое событие несёт уникальный event_id (UUID или ULID) - он попадает в конверт в момент создания факта, в домене, а не в consumer-е (см. структуру доменного события). Этот идентификатор - ключ дедупликации. Перед обработкой проверяем: видели ли мы это событие раньше? Если да - пропускаем. Если нет - обрабатываем и запоминаем. Обрати внимание: «idempotency key» его называют по традиции, но идемпотентной операцию он не делает - см. врезку выше.
Inbox-таблица: дедупликация обработки
Для дедупликации нужна таблица в базе данных:
CREATE TABLE processed_events (
event_id VARCHAR(64) NOT NULL,
event_type VARCHAR(128) NOT NULL,
handler VARCHAR(128) NOT NULL,
processed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (event_id, handler)
);
-- Индекс для очистки старых записей
CREATE INDEX idx_processed_events_processed_at
ON processed_events (processed_at);
Ключ здесь составной, и это не педантичность. Одно и то же событие обрабатывают
несколько подписчиков: achievement-сервис и analytics-сервис - разные
обработчики, каждый должен выполнить свою работу ровно один раз. При
PRIMARY KEY (event_id) первый успевший обработчик занимает ключ, а второй
видит «уже обработано» и молча пропускает свою часть - то есть ровно та потеря,
от которой таблица защищает.
⚠️ «Пока обработчик один» - не аргумент
Соблазн взять
PRIMARY KEY (event_id)«для простоты, у нас один подписчик» велик, но второй подписчик появляется позже и без миграции. Сбой при этом не громкий: ошибок нет, событие считается обработанным, просто чья-то работа не сделана. Составной ключ ничего не усложняет - он такой же индекс, только из двух колонок.
Check-Process-Mark: паттерн обработки
Основной паттерн: проверить - обработать - отметить.
// ProcessedEventsRepo отвечает за дедупликацию событий.
type ProcessedEventsRepo struct {
db *sql.DB
}
// AlreadyProcessed проверяет, было ли событие обработано.
func (r *ProcessedEventsRepo) AlreadyProcessed(ctx context.Context, eventID, handler string) (bool, error) {
var exists bool
err := r.db.QueryRowContext(ctx,
`SELECT EXISTS(SELECT 1 FROM processed_events WHERE event_id = $1 AND handler = $2)`,
eventID, handler,
).Scan(&exists)
return exists, err
}
// MarkProcessed отмечает событие как обработанное.
func (r *ProcessedEventsRepo) MarkProcessed(ctx context.Context, eventID, handler, eventType string) error {
_, err := r.db.ExecContext(ctx,
`INSERT INTO processed_events (event_id, event_type, handler)
VALUES ($1, $2, $3)
ON CONFLICT (event_id, handler) DO NOTHING`,
eventID, eventType, handler,
)
return err
}
<?php
// src/Infrastructure/Inbox/ProcessedEventsRepository.php
declare(strict_types=1);
namespace App\Infrastructure\Inbox;
use App\Application\Port\ProcessedEventsRepository as ProcessedEventsRepositoryPort;
use Doctrine\DBAL\Connection;
// Doctrine DBAL - тонкая прослойка над PDO. Симметрична database/sql из Go.
final class ProcessedEventsRepository implements ProcessedEventsRepositoryPort
{
public function __construct(
private readonly Connection $connection,
) {}
public function alreadyProcessed(string $eventId, string $handler): bool
{
$row = $this->connection->fetchOne(
'SELECT EXISTS(SELECT 1 FROM processed_events WHERE event_id = :eid AND handler = :h)',
['eid' => $eventId, 'h' => $handler],
);
return (bool) $row;
}
public function markProcessed(string $eventId, string $handler, string $eventType): void
{
// ON CONFLICT DO NOTHING - Postgres-specific.
// На MySQL: INSERT IGNORE INTO ...
$this->connection->executeStatement(
'INSERT INTO processed_events (event_id, event_type, handler)
VALUES (:eid, :etype, :h)
ON CONFLICT (event_id, handler) DO NOTHING',
['eid' => $eventId, 'etype' => $eventType, 'h' => $handler],
);
}
}
# infrastructure/inbox/processed_events_repo.py
from psycopg import Connection
class ProcessedEventsRepo:
"""Отвечает за дедупликацию событий.
psycopg (v3) - тонкая прослойка над libpq. Симметричен database/sql из Go.
"""
def __init__(self, conn: Connection) -> None:
self._conn = conn
def already_processed(self, event_id: str, handler: str) -> bool:
"""Проверяет, было ли событие обработано."""
with self._conn.transaction(), self._conn.cursor() as cur:
cur.execute(
"SELECT EXISTS(SELECT 1 FROM processed_events WHERE event_id = %s AND handler = %s)",
(event_id, handler),
)
row = cur.fetchone()
return bool(row and row[0])
def mark_processed(self, event_id: str, handler: str, event_type: str) -> None:
"""Отмечает событие как обработанное."""
# ON CONFLICT DO NOTHING - Postgres-specific.
# Явная транзакция: выход из with без исключения - COMMIT, с исключением - ROLLBACK.
with self._conn.transaction(), self._conn.cursor() as cur:
cur.execute(
"""INSERT INTO processed_events (event_id, event_type, handler)
VALUES (%s, %s, %s)
ON CONFLICT (event_id, handler) DO NOTHING""",
(event_id, event_type, handler),
)
Обработчик события использует этот репозиторий:
// HandleLessonCompleted обрабатывает событие завершения урока.
// Защищает от повтора, только если обработка и отметка не разорваны сбоем:
// упадём между шагами 2 и 3 - при повторе логика выполнится снова.
// Надёжный вариант - HandleAtomically ниже.
func (h *AchievementHandler) HandleLessonCompleted(ctx context.Context, evt LessonCompleted) error {
const handlerName = "achievement_checker"
// 1. Check: уже обработано?
seen, err := h.inbox.AlreadyProcessed(ctx, evt.EventID, handlerName)
if err != nil {
return fmt.Errorf("inbox check: %w", err)
}
if seen {
slog.InfoContext(ctx, "event already processed, skipping",
slog.String("event_id", evt.EventID),
slog.String("handler", handlerName),
)
return nil
}
// 2. Process: выполняем бизнес-логику
if err := h.checkAndGrantAchievements(ctx, evt.UserID, evt.LessonID); err != nil {
return fmt.Errorf("grant achievements: %w", err)
}
// 3. Mark: запоминаем
if err := h.inbox.MarkProcessed(ctx, evt.EventID, handlerName, evt.Type); err != nil {
return fmt.Errorf("inbox mark: %w", err)
}
return nil
}
<?php
// src/Application/Subscriber/AchievementSubscriber.php
declare(strict_types=1);
namespace App\Application\Subscriber;
use App\Application\Port\ProcessedEventsRepository;
use App\Domain\Event\LessonCompleted;
use Psr\Log\LoggerInterface;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;
#[AsMessageHandler]
final class AchievementSubscriber
{
private const HANDLER_NAME = 'achievement_checker';
public function __construct(
private readonly ProcessedEventsRepository $inbox,
private readonly AchievementGranter $granter,
private readonly LoggerInterface $logger,
) {}
public function __invoke(LessonCompleted $event): void
{
// 1. Check: уже обработано?
if ($this->inbox->alreadyProcessed($event->id, self::HANDLER_NAME)) {
$this->logger->info('event already processed, skipping', [
'event_id' => $event->id,
'handler' => self::HANDLER_NAME,
]);
return;
}
// 2. Process: выполняем бизнес-логику
$this->granter->grantAchievements($event->userId, $event->lessonId);
// 3. Mark: запоминаем
$this->inbox->markProcessed($event->id, self::HANDLER_NAME, $event->eventType());
}
}
# application/subscriber/achievement_handler.py
import logging
log = logging.getLogger(__name__)
class AchievementHandler:
HANDLER_NAME = "achievement_checker"
def __init__(self, inbox: ProcessedEventsRepo, granter: AchievementGranter) -> None:
self._inbox = inbox
self._granter = granter
def handle_lesson_completed(self, evt: LessonCompleted) -> None:
"""Обрабатывает событие завершения урока.
Защищает от повтора, только если обработка и отметка не разорваны сбоем:
упадём между шагами 2 и 3 - при повторе логика выполнится снова.
Надёжный вариант - handle_atomically ниже.
Ошибки не возвращаются, а летят исключениями из inbox и granter - вызывающий
(consumer) по ним решает, делать ли nack/retry.
"""
# 1. Check: уже обработано?
if self._inbox.already_processed(evt.event_id, self.HANDLER_NAME):
log.info(
"event already processed, skipping",
extra={"event_id": evt.event_id, "handler": self.HANDLER_NAME},
)
return
# 2. Process: выполняем бизнес-логику
self._granter.check_and_grant_achievements(evt.user_id, evt.lesson_id)
# 3. Mark: запоминаем
self._inbox.mark_processed(evt.event_id, self.HANDLER_NAME, evt.event_type)
Атомарная отметка: INSERT ON CONFLICT DO NOTHING
Обратите внимание на ON CONFLICT DO NOTHING в MarkProcessed. Это критически важно. Если два воркера одновременно получили одно и то же событие, оба пройдут проверку AlreadyProcessed (оба получат false) и оба начнут обработку. ON CONFLICT DO NOTHING гарантирует, что вставка пройдёт только у первого. Но бизнес-логика всё равно выполнится дважды.
Для полной защиты от гонки нужна транзакция с блокировкой:
// HandleAtomically обрабатывает событие в одной транзакции с отметкой.
func (h *AchievementHandler) HandleAtomically(ctx context.Context, evt LessonCompleted) error {
tx, err := h.db.BeginTx(ctx, nil)
if err != nil {
return fmt.Errorf("begin tx: %w", err)
}
defer tx.Rollback()
// Пытаемся вставить - если уже есть, rows == 0
res, err := tx.ExecContext(ctx,
`INSERT INTO processed_events (event_id, event_type, handler)
VALUES ($1, $2, $3)
ON CONFLICT (event_id, handler) DO NOTHING`,
evt.EventID, evt.Type, "achievement_checker",
)
if err != nil {
return fmt.Errorf("inbox insert: %w", err)
}
rows, _ := res.RowsAffected()
if rows == 0 {
// Событие уже обработано другим воркером
return nil
}
// Бизнес-логика внутри той же транзакции
if err := h.grantAchievementsInTx(ctx, tx, evt.UserID, evt.LessonID); err != nil {
return fmt.Errorf("grant: %w", err)
}
return tx.Commit()
}
<?php
// src/Application/Subscriber/AchievementHandlerAtomic.php
declare(strict_types=1);
namespace App\Application\Subscriber;
use App\Domain\Event\LessonCompleted;
use Doctrine\DBAL\Connection;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;
#[AsMessageHandler]
final class AchievementHandlerAtomic
{
private const HANDLER_NAME = 'achievement_checker';
public function __construct(
private readonly Connection $connection,
private readonly AchievementGranter $granter,
) {}
public function __invoke(LessonCompleted $event): void
{
$this->connection->transactional(function (Connection $tx) use ($event): void {
// Пытаемся вставить - если уже есть, affectedRows == 0
$affected = $tx->executeStatement(
'INSERT INTO processed_events (event_id, event_type, handler)
VALUES (:eid, :etype, :h)
ON CONFLICT (event_id, handler) DO NOTHING',
['eid' => $event->id, 'etype' => $event->eventType(), 'h' => self::HANDLER_NAME],
);
if ($affected === 0) {
// Событие уже обработано другим воркером
return;
}
// Бизнес-логика внутри той же транзакции
$this->granter->grantInTransaction($tx, $event->userId, $event->lessonId);
});
}
}
# application/subscriber/achievement_handler_atomic.py
from psycopg import Connection
class AchievementHandlerAtomic:
HANDLER_NAME = "achievement_checker"
def __init__(self, conn: Connection, granter: AchievementGranter) -> None:
self._conn = conn
self._granter = granter
def handle_atomically(self, evt: LessonCompleted) -> None:
"""Обрабатывает событие в одной транзакции с отметкой."""
# Явная транзакция: выход из with без исключения - COMMIT,
# с исключением - ROLLBACK (откатятся и отметка, и бизнес-логика).
with self._conn.transaction(), self._conn.cursor() as cur:
# Пытаемся вставить - если уже есть, rowcount == 0
cur.execute(
"""INSERT INTO processed_events (event_id, event_type, handler)
VALUES (%s, %s, %s)
ON CONFLICT (event_id, handler) DO NOTHING""",
(evt.event_id, evt.event_type, self.HANDLER_NAME),
)
if cur.rowcount == 0:
# Событие уже обработано другим воркером
return
# Бизнес-логика внутри той же транзакции - через тот же курсор
self._granter.grant_in_tx(cur, evt.user_id, evt.lesson_id)
Теперь отметка и бизнес-логика атомарны. Если бизнес-логика упала - откатится и отметка, и событие будет обработано заново.
Естественная идемпотентность
Не все операции требуют inbox-таблицы, и это предпочтительный случай: если операция безопасна к повтору сама по себе, дедупликация не нужна вовсе - а значит нет и таблицы, которую можно потерять, и ключа, который можно подобрать неверно.
UPSERT вместо INSERT. Если подписчик записывает результат в таблицу, используйте INSERT ... ON CONFLICT DO UPDATE:
// RecordLessonCompletion записывает факт завершения урока.
// completedAt берём из события (evt.OccurredAt()), а не now(): тогда повтор
// пишет то же значение. Идемпотентна: повтор не меняет ни количество строк,
// ни completed_at.
func (r *AnalyticsRepo) RecordLessonCompletion(ctx context.Context, userID, lessonID int64, completedAt time.Time) error {
_, err := r.db.ExecContext(ctx,
`INSERT INTO lesson_completions (user_id, lesson_id, completed_at)
VALUES ($1, $2, $3)
ON CONFLICT (user_id, lesson_id)
DO UPDATE SET completed_at = EXCLUDED.completed_at`,
userID, lessonID, completedAt,
)
return err
}
<?php
// src/Infrastructure/Analytics/AnalyticsRepository.php
declare(strict_types=1);
namespace App\Infrastructure\Analytics;
use Doctrine\DBAL\Connection;
use DateTimeImmutable;
final class AnalyticsRepository
{
public function __construct(
private readonly Connection $connection,
) {}
// $completedAt берём из события ($event->occurredAt), а не now(): тогда повтор
// пишет то же значение. Идемпотентна: повтор не меняет ни количество строк,
// ни completed_at.
public function recordLessonCompletion(int $userId, int $lessonId, DateTimeImmutable $completedAt): void
{
$this->connection->executeStatement(
'INSERT INTO lesson_completions (user_id, lesson_id, completed_at)
VALUES (:uid, :lid, :at)
ON CONFLICT (user_id, lesson_id)
DO UPDATE SET completed_at = EXCLUDED.completed_at',
['uid' => $userId, 'lid' => $lessonId, 'at' => $completedAt->format(DATE_ATOM)],
);
}
}
# infrastructure/analytics/analytics_repo.py
from datetime import datetime
from psycopg import Connection
class AnalyticsRepo:
def __init__(self, conn: Connection) -> None:
self._conn = conn
def record_lesson_completion(self, user_id: int, lesson_id: int, completed_at: datetime) -> None:
"""Записывает факт завершения урока.
completed_at берём из события (evt.occurred_at), а не now(): тогда повтор
пишет то же значение. Идемпотентна: повтор не меняет ни количество строк,
ни completed_at.
"""
with self._conn.transaction(), self._conn.cursor() as cur:
cur.execute(
"""INSERT INTO lesson_completions (user_id, lesson_id, completed_at)
VALUES (%s, %s, %s)
ON CONFLICT (user_id, lesson_id)
DO UPDATE SET completed_at = EXCLUDED.completed_at""",
(user_id, lesson_id, completed_at),
)
State machine transitions. Если статус может двигаться только вперёд (pending -> paid -> shipped), повторная попытка перевести из pending в paid ничего не сломает, а попытка перевести из shipped в paid просто не пройдёт:
// AdvanceOrderStatus переводит заказ на следующий статус.
// Идемпотентна: WHERE clause гарантирует, что переход произойдёт только один раз.
func (r *OrderRepo) AdvanceOrderStatus(ctx context.Context, orderID int64, from, to string) error {
res, err := r.db.ExecContext(ctx,
`UPDATE orders SET status = $1, updated_at = now()
WHERE id = $2 AND status = $3`,
to, orderID, from,
)
if err != nil {
return err
}
rows, _ := res.RowsAffected()
if rows == 0 {
slog.InfoContext(ctx, "order already advanced past this status",
slog.Int64("order_id", orderID),
slog.String("expected_from", from),
)
}
return nil
}
<?php
// src/Infrastructure/Order/OrderRepository.php
declare(strict_types=1);
namespace App\Infrastructure\Order;
use Doctrine\DBAL\Connection;
use Psr\Log\LoggerInterface;
final class OrderRepository
{
public function __construct(
private readonly Connection $connection,
private readonly LoggerInterface $logger,
) {}
// Идемпотентна: WHERE clause гарантирует, что переход произойдёт только один раз.
public function advanceStatus(int $orderId, string $from, string $to): void
{
$affected = $this->connection->executeStatement(
'UPDATE orders SET status = :to, updated_at = now()
WHERE id = :oid AND status = :from',
['to' => $to, 'oid' => $orderId, 'from' => $from],
);
if ($affected === 0) {
$this->logger->info('order already advanced past this status', [
'order_id' => $orderId,
'expected_from' => $from,
]);
}
}
}
# infrastructure/order/order_repo.py
import logging
from psycopg import Connection
log = logging.getLogger(__name__)
class OrderRepo:
def __init__(self, conn: Connection) -> None:
self._conn = conn
def advance_order_status(self, order_id: int, from_status: str, to_status: str) -> None:
"""Переводит заказ на следующий статус.
Идемпотентна: WHERE clause гарантирует, что переход произойдёт только один раз.
"""
with self._conn.transaction(), self._conn.cursor() as cur:
cur.execute(
"""UPDATE orders SET status = %s, updated_at = now()
WHERE id = %s AND status = %s""",
(to_status, order_id, from_status),
)
affected = cur.rowcount
if affected == 0:
log.info(
"order already advanced past this status",
extra={"order_id": order_id, "expected_from": from_status},
)
TTL для processed_events
Таблица processed_events растёт бесконечно. События старше определённого возраста можно безопасно удалять - вероятность получить событие двухнедельной давности стремится к нулю:
// CleanupOldEvents удаляет записи старше ttl.
// Запускайте по cron раз в сутки.
func (r *ProcessedEventsRepo) CleanupOldEvents(ctx context.Context, ttl time.Duration) (int64, error) {
res, err := r.db.ExecContext(ctx,
`DELETE FROM processed_events WHERE processed_at < $1`,
time.Now().Add(-ttl),
)
if err != nil {
return 0, err
}
return res.RowsAffected()
}
<?php
// src/Application/Cron/CleanupProcessedEventsCommand.php
declare(strict_types=1);
namespace App\Application\Cron;
use Doctrine\DBAL\Connection;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use DateTimeImmutable;
// Запускается из cron: `bin/console app:cleanup-processed-events --ttl-days=14`.
// В Symfony альтернатива - Scheduler component (symfony/scheduler).
#[AsCommand(name: 'app:cleanup-processed-events')]
final class CleanupProcessedEventsCommand extends Command
{
public function __construct(
private readonly Connection $connection,
) {
parent::__construct();
}
protected function execute(InputInterface $input, OutputInterface $output): int
{
$ttlDays = 14;
$threshold = (new DateTimeImmutable())->modify(sprintf('-%d days', $ttlDays));
$affected = $this->connection->executeStatement(
'DELETE FROM processed_events WHERE processed_at < :threshold',
['threshold' => $threshold->format('Y-m-d H:i:s')],
);
$output->writeln(sprintf('deleted %d rows', $affected));
return Command::SUCCESS;
}
}
# application/cron/cleanup_processed_events.py
from datetime import datetime, timedelta, timezone
from psycopg import Connection
class ProcessedEventsRepo:
def __init__(self, conn: Connection) -> None:
self._conn = conn
def cleanup_old_events(self, ttl: timedelta) -> int:
"""Удаляет записи старше ttl и возвращает число удалённых.
Запускайте по cron раз в сутки (или из Celery beat / APScheduler).
"""
threshold = datetime.now(timezone.utc) - ttl
with self._conn.transaction(), self._conn.cursor() as cur:
cur.execute(
"DELETE FROM processed_events WHERE processed_at < %s",
(threshold,),
)
return cur.rowcount
Разумный TTL - от 7 до 30 дней, в зависимости от того, как далеко назад вы можете replay-ить события.
HTTP API: заголовок Idempotency-Key
Idempotency нужна не только внутри event-driven системы. HTTP-клиенты тоже могут повторять запросы (таймаут, retry). Stripe популяризировал паттерн с заголовком Idempotency-Key:
// CachedResponse - сохранённый ответ: статус, заголовки и тело.
type CachedResponse struct {
StatusCode int
Header http.Header
Body []byte
}
// IdempotencyRepo хранит ключи в таблице
// idempotency_keys(key PRIMARY KEY, status, status_code, headers, body, created_at).
type IdempotencyRepo interface {
// Reserve атомарно занимает ключ:
// INSERT INTO idempotency_keys (key, status) VALUES ($1, 'in_progress')
// ON CONFLICT (key) DO NOTHING
// reserved=true - ключ наш. Иначе cached - сохранённый ответ
// или nil, если первый запрос с этим ключом ещё выполняется.
Reserve(ctx context.Context, key string) (reserved bool, cached *CachedResponse, err error)
// Complete сохраняет ответ и переводит ключ в статус done.
Complete(ctx context.Context, key string, resp CachedResponse) error
// Release удаляет бронь, чтобы повтор мог выполниться заново.
Release(ctx context.Context, key string) error
}
// IdempotencyMiddleware проверяет заголовок Idempotency-Key.
// Если запрос с таким ключом уже обработан - возвращает сохранённый ответ.
func IdempotencyMiddleware(repo IdempotencyRepo) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
key := r.Header.Get("Idempotency-Key")
if key == "" {
next.ServeHTTP(w, r)
return
}
// 1. Занимаем ключ ДО вызова handler-а. Просто проверить кэш мало:
// клиент обычно повторяет запрос по таймауту, пока первый ещё
// выполняется, и оба прошли бы проверку - двойное списание.
reserved, cached, err := repo.Reserve(r.Context(), key)
if err != nil {
http.Error(w, "idempotency store unavailable", http.StatusServiceUnavailable)
return
}
if !reserved {
if cached == nil {
// Первый запрос с этим ключом ещё в работе
http.Error(w, "request with this Idempotency-Key is in progress", http.StatusConflict)
return
}
// 2. Повтор: отдаём сохранённый ответ целиком, вместе с заголовками
for k, v := range cached.Header {
w.Header()[k] = v
}
w.WriteHeader(cached.StatusCode)
_, _ = w.Write(cached.Body)
return
}
// 3. Ключ наш: выполняем запрос и записываем ответ
rec := &responseRecorder{ResponseWriter: w, statusCode: http.StatusOK}
next.ServeHTTP(rec, r)
// 5xx не сохраняем: снимаем бронь, чтобы повтор мог выполниться
if rec.statusCode >= http.StatusInternalServerError {
_ = repo.Release(r.Context(), key)
return
}
// Если запись упадёт, ключ останется in_progress: такие брони чистит TTL
_ = repo.Complete(r.Context(), key, CachedResponse{
StatusCode: rec.statusCode,
Header: w.Header().Clone(),
Body: rec.body.Bytes(),
})
})
}
}
// responseRecorder пропускает ответ клиенту и параллельно копит его для сохранения
type responseRecorder struct {
http.ResponseWriter
statusCode int
body bytes.Buffer
}
func (r *responseRecorder) WriteHeader(code int) {
r.statusCode = code
r.ResponseWriter.WriteHeader(code)
}
func (r *responseRecorder) Write(b []byte) (int, error) {
r.body.Write(b)
return r.ResponseWriter.Write(b)
}
<?php
// src/Infrastructure/Http/IdempotencyListener.php
declare(strict_types=1);
namespace App\Infrastructure\Http;
use App\Application\Port\IdempotencyRepository;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\Event\ResponseEvent;
// В Symfony роль HTTP-middleware из Go играют kernel-listener'ы.
// onRequest занимает ключ (или отдаёт сохранённый ответ), onResponse сохраняет ответ.
//
// IdempotencyRepository:
// reserve(key): bool - INSERT INTO idempotency_keys (key, status)
// VALUES (:key, 'in_progress') ON CONFLICT (key) DO NOTHING
// getCachedResponse(key): ?CachedResponse - null, пока первый запрос выполняется
// complete(key, status, headers, body), release(key)
final class IdempotencyListener
{
private const RESERVED_ATTR = '_idempotency_reserved';
public function __construct(
private readonly IdempotencyRepository $repo,
) {}
#[AsEventListener(event: RequestEvent::class)]
public function onRequest(RequestEvent $event): void
{
$request = $event->getRequest();
$key = $request->headers->get('Idempotency-Key');
if ($key === null) {
return;
}
// Занимаем ключ ДО контроллера: повтор по таймауту приходит,
// пока первый запрос ещё выполняется
if ($this->repo->reserve($key)) {
$request->attributes->set(self::RESERVED_ATTR, true);
return;
}
$cached = $this->repo->getCachedResponse($key);
if ($cached === null) {
// Первый запрос с этим ключом ещё в работе
$event->setResponse(new Response('request with this Idempotency-Key is in progress', 409));
return;
}
// Повтор: отдаём сохранённый ответ вместе с заголовками - дальше kernel не идёт
$event->setResponse(new Response($cached->body, $cached->statusCode, $cached->headers));
}
#[AsEventListener(event: ResponseEvent::class)]
public function onResponse(ResponseEvent $event): void
{
$request = $event->getRequest();
$key = $request->headers->get('Idempotency-Key');
// Сохраняем только ответ запроса, который сам занял ключ
if ($key === null || $request->attributes->get(self::RESERVED_ATTR) !== true) {
return;
}
$response = $event->getResponse();
if ($response->getStatusCode() >= 500) {
// 5xx не сохраняем: снимаем бронь, чтобы повтор мог выполниться
$this->repo->release($key);
return;
}
$this->repo->complete(
$key,
$response->getStatusCode(),
$response->headers->all(),
(string) $response->getContent(),
);
}
}
# infrastructure/http/idempotency_middleware.py
from dataclasses import dataclass
from http import HTTPStatus
from typing import Callable, Iterable, Protocol
WSGIApp = Callable[[dict, Callable], Iterable[bytes]]
@dataclass(frozen=True, slots=True)
class CachedResponse:
status_code: int
headers: list[tuple[str, str]]
body: bytes
class IdempotencyRepo(Protocol):
# INSERT INTO idempotency_keys (key, status) VALUES (%s, 'in_progress')
# ON CONFLICT (key) DO NOTHING; True - ключ занят нами
def reserve(self, key: str) -> bool: ...
# None, пока первый запрос с этим ключом выполняется
def get_cached_response(self, key: str) -> CachedResponse | None: ...
def complete(self, key: str, response: CachedResponse) -> None: ...
def release(self, key: str) -> None: ...
class IdempotencyMiddleware:
"""Проверяет заголовок Idempotency-Key.
Если запрос с таким ключом уже обработан - возвращает сохранённый ответ.
Фреймворк-независимый WSGI-вариант: в FastAPI/Starlette это BaseHTTPMiddleware,
в Django - класс middleware с __call__(request).
"""
def __init__(self, app: WSGIApp, repo: IdempotencyRepo) -> None:
self._app = app
self._repo = repo
def __call__(self, environ: dict, start_response: Callable) -> Iterable[bytes]:
# WSGI кладёт заголовки в environ как HTTP_<ИМЯ>
key = environ.get("HTTP_IDEMPOTENCY_KEY", "")
if not key:
return self._app(environ, start_response)
# Занимаем ключ ДО вызова приложения: повтор по таймауту приходит,
# пока первый запрос ещё выполняется
if not self._repo.reserve(key):
cached = self._repo.get_cached_response(key)
if cached is None:
start_response("409 Conflict", [("Content-Type", "text/plain")])
return [b"request with this Idempotency-Key is in progress"]
# Повтор: отдаём сохранённый ответ вместе с заголовками
phrase = HTTPStatus(cached.status_code).phrase
start_response(f"{cached.status_code} {phrase}", cached.headers)
return [cached.body]
# Оборачиваем start_response для захвата статуса и заголовков ответа
captured: dict = {}
def recording_start_response(status: str, headers: list, exc_info=None):
captured["status"] = status
captured["headers"] = list(headers)
return start_response(status, headers, exc_info)
try:
body = b"".join(self._app(environ, recording_start_response))
except Exception:
self._repo.release(key) # упали - повтор должен выполниться заново
raise
status_code = int(captured.get("status", "200 OK").split()[0])
if status_code >= 500:
self._repo.release(key) # 5xx не сохраняем
else:
self._repo.complete(key, CachedResponse(status_code, captured.get("headers", []), body))
return [body]
🚫 Устойчивость к повтору - не оптимизация, а обязательное требование
В at-least-once системе каждый подписчик обязан корректно переживать повторную доставку. Без этого повторы дадут дубли данных, двойные списания и повреждённое состояние.
Достигается это двумя способами, и они не равноценны: идемпотентная операция безопасна к повтору сама (UPSERT, установка целевого состояния, ключ операции на стороне внешнего API), дедупликация через inbox делает безопасной обработку конкретного события по записи в базе. Первое надёжнее, потому что не зависит от сохранности этой записи; второе - способ прикрыть то, что переписать нельзя.
Проектировать это стоит с самого начала: добавлять потом значительно дороже, особенно если операции уже написаны через инкременты.
Типичные ошибки
- Проверка «не обработано ли» отдельно от обработки - две reads + два writes без транзакции. Между check и mark два инстанса видят «не обработано», оба делают работу. Атомарность через
INSERT ... ON CONFLICT DO NOTHING+ RETURNING в одной транзакции с бизнес-логикой. - Idempotency-key = таймстамп клиента - два разных POST от одного юзера в одну миллисекунду дают одинаковый ключ; одно из действий теряется. Используй UUID, генерируемый клиентом до запроса.
- Idempotency-store разделён с бизнес-БД - отметка о processing идёт в Redis, бизнес-данные в PostgreSQL. Redis перезагрузился без AOF → дубли. Idempotency живёт в той же БД, что и бизнес-операция; одна транзакция.
- Различные subscriber-ы пишут в одну
processed_eventsбез поляhandler- subscriber A обработал, отметил; subscriber B видит «уже обработано» и пропускает свою работу. Ключ дедупа =(event_id, handler_name), не толькоevent_id. - UPSERT вместо «начислить +10 бонусов» - повторное событие → бонусы перезаписываются тем же значением (это корректно). Но если бы было
UPDATE balance = balance + 10- двойное начисление. Понимай: идемпотентность через UPSERT работает для установки значения, не для инкремента. - Idempotency только в HTTP-слое - клиент шлёт повторный POST с тем же
Idempotency-Key, HTTP-middleware возвращает кэшированный ответ. Но внутреннее событие тоже опубликовано дважды - а subscriber не имеет своей дедупликации. Дедуп нужен на каждом узле at-least-once-цепочки. - Сравнение
processed_atдля «свежести» - «не обработать события старше 1 часа». При replay из брокера старые события массово пропускаются и не обновляют read-модели. Не путай идемпотентность с фильтрацией.
Мини-задание
- Создай таблицу
processed_eventsс полямиevent_id,handler,event_type,processed_at - Реализуй атомарный check-process-mark паттерн с
INSERT ON CONFLICT DO NOTHINGвнутри транзакции - Перепиши один из своих обработчиков, чтобы он использовал естественную идемпотентность (UPSERT или state machine)
- Добавь горутину очистки записей старше 14 дней
- Напиши unit-тест: вызови обработчик дважды с одним event_id и убедись, что бизнес-логика выполнилась один раз