К содержимому
Войти

Python Road Map

🔁 Идемпотентность

Операция идемпотентна, если её повтор ничего не меняет. Два одинаковых запроса оставляют систему в том же состоянии, что и один. В распределённой системе повторы неизбежны, поэтому каждая операция с побочным эффектом обязана их переживать, иначе ретрай клиента однажды спишет деньги дважды. Как ведут себя методы HTTP и что такое заголовок Idempotency-Key, разобрано на страницах про HTTP и REST API. Здесь о том, как идемпотентность держится по всей цепочке сервисов и как её делают в коде на проде

🧠 Откуда берутся повторы

Сервис заказов отправил запрос в оплату и не дождался ответа за 500 мс. Возможны два случая: запрос потерялся по дороге, и деньги не списаны, или оплата всё сделала, а потерялся ответ. Отправитель эти случаи не различает. Если он не повторит, в первом случае заказ останется неоплаченным. Если повторит, во втором случае деньги спишутся дважды. Поэтому отправитель повторяет, а получатель распознаёт повтор и не выполняет работу второй раз

Повторы приходят отовсюду:

  • пользователь дважды нажал «Оплатить» или отправил форму из двух вкладок
  • мобильное приложение повторило запрос после обрыва связи
  • SDK, шлюз или сам сервис сделал ретрай после таймаута
  • брокер доставил сообщение второй раз после рестарта потребителя
  • крон или воркер перезапустился посреди пачки и начал её заново

«Ровно один раз» на практике собирают из двух частей: доставка at-least-once плюс идемпотентный получатель. Сообщение может прийти три раза, а эффект будет один. Как это устроено в брокерах, на странице «Гарантии доставки»

🧭 Три способа сделать операцию идемпотентной

Ключ идемпотентности нужен не всегда. Сначала стоит проверить, не делается ли операция идемпотентной бесплатно

СпособПримерКогда подходит
Операция идемпотентна самаupdate orders set status = 'paid' where id = $1 and status = 'pending'Переход статуса, установка значения, upsert
Уникальный бизнес-ключКолонка client_order_id с уникальным индексом, повтор падает на unique violationУ сущности есть естественный идентификатор от клиента
Ключ идемпотентности с сохранённым ответомТаблица idempotency_keys, повтор получает ответ первого запросаОбщий случай: создание, списание, отправка письма

Первый способ работает для переходов по конечному автомату. Заказ переходит в paid только из pending, и повтор обновит ноль строк. По этому нулю сервис понимает, что работа уже сделана, и отвечает успехом, а не ошибкой. Хуже с операциями-приращениями: «прибавить 100 к балансу» повторять нельзя. Их переписывают в записи с уникальным id, например строку платежа, а баланс считают по этим строкам

Дальше речь о третьем способе: он подходит к любой операции

🔑 Ключ: кто создаёт и сколько хранить

Ключ создаёт клиент, один раз на намерение пользователя. Человек нажал «Оплатить» — приложение сгенерировало UUID и отправляет его со всеми попытками этого платежа. Новый платёж — новый ключ. Если ключ генерируется внутри функции ретрая, каждая попытка приходит с новым ключом, и защиты нет

Сервер проверяет ключ не сам по себе, а в связке:

  • Область. Ключ уникален в пределах пользователя или клиента API: первичный ключ таблицы — (user_id, key). Без этого два клиента со случайно совпавшими ключами мешают друг другу, а в худшем случае один получит сохранённый ответ другого, с чужими данными
  • Отпечаток запроса. Рядом с ключом хранят хэш тела. Повтор с тем же ключом и другим телом — ошибка клиента, сервер отвечает 422 и ничего не выполняет. Так предлагает черновик IETF о заголовке Idempotency-Key, и так же сверяют повтор с первым запросом Stripe и AWS
  • Срок жизни. Ключи удаляют по возрасту. Stripe удаляет их не раньше чем через 24 часа. Брандур Лич в разборе того, как сделать ключи в стиле Stripe на Postgres, советует 72 часа, чтобы сбой, найденный после выходных, ещё можно было дочинить. Ключ должен жить дольше, чем клиент может повторять. Если сообщение может вернуться из DLQ через неделю, суточный срок не защитит

Ключ идемпотентности не равен request id и trace id. Те новые на каждую попытку и нужны для логов. Ключ общий для всех попыток одной операции. И в ключ не кладут персональные данные вроде email: он оседает в логах и таблицах

🛠️ Когда всё в одной базе

Самый частый случай: операция меняет только свою базу. Тогда ключ, изменение и сохранённый ответ пишутся в одной транзакции. AWS в статье о безопасных ретраях требует этого прямо, иначе возможны ключ без созданного ресурса и ресурс без ключа

Первой командой транзакция вставляет ключ через insert ... on conflict do nothing. Если вставка прошла, сервис создаёт заказ, записывает ответ в строку ключа и коммитит. Если вставка вернула ноль строк, ключ уже есть: сервис сверяет хэш тела и отдаёт сохранённый ответ

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

Go · Создание заказа с ключом идемпотентности на pgx

func createOrder(ctx context.Context, db *pgxpool.Pool, userID int64, key, body string) (int, string, error) {
	hash := sha256.Sum256([]byte(body))
	tx, err := db.Begin(ctx)
	if err != nil {
		return 0, "", err
	}
	defer tx.Rollback(ctx)

	// первым шагом занимаем ключ: дубль встанет на уникальном индексе и дождётся коммита
	tag, err := tx.Exec(ctx, `insert into idempotency_keys (user_id, key, request_hash)
		values ($1, $2, $3) on conflict do nothing`, userID, key, hash[:])
	if err != nil {
		return 0, "", err
	}
	if tag.RowsAffected() == 0 {
		var saved []byte
		var code int
		var resp string
		err := tx.QueryRow(ctx, `select request_hash, response_code, response_body
			from idempotency_keys where user_id = $1 and key = $2`, userID, key).Scan(&saved, &code, &resp)
		if err != nil {
			return 0, "", err
		}
		if !bytes.Equal(saved, hash[:]) {
			return 422, `{"error":"ключ уже использован с другим телом"}`, nil
		}
		return code, resp, nil // повтор: отдаём сохранённый ответ
	}

	var id int64
	err = tx.QueryRow(ctx, `insert into orders (user_id, body) values ($1, $2) returning id`,
		userID, body).Scan(&id)
	if err != nil {
		return 0, "", err
	}
	resp := fmt.Sprintf(`{"order_id":%d}`, id)
	_, err = tx.Exec(ctx, `update idempotency_keys set response_code = 201, response_body = $3
		where user_id = $1 and key = $2`, userID, key, resp)
	if err != nil {
		return 0, "", err
	}
	return 201, resp, tx.Commit(ctx) // ключ, заказ и ответ фиксируются вместе
}

Таблица ключей — первичный ключ (user_id, key), request_hash bytea, код и тело ответа, created_at для очистки. Запуск на PostgreSQL 16: десять горутин одновременно отправили один запрос с ключом a1b2, потом пришли два контрольных запроса:

10 одновременных запросов: map[201 {"order_id":1}:10] заказов: 1
тот же ключ, другое тело: 422 {"error":"ключ уже использован с другим телом"}
тот же ключ, другой пользователь: 201 {"order_id":2}

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

🌍 Когда операция зовёт внешний сервис

Транзакцию нельзя держать открытой, пока идёт запрос в платёжный шлюз: он занимает секунды, а может и не вернуться. Поэтому операцию режут на атомарные фазы. Каждая фаза — короткая транзакция в своей базе, между фазами стоят вызовы наружу. В строке ключа хранится точка восстановления: какая фаза пройдена последней

фаза 1, транзакция: вставить ключ, создать заказ в статусе pending,
                    recovery_point = order_created, locked_at = now()
вызов наружу:       списать деньги у провайдера с ключом "charge-<id ключа>"
фаза 2, транзакция: сохранить id платежа, статус paid, ответ 201,
                    recovery_point = finished, locked_at = null

Если сервис упал после списания, но до фазы 2, повтор клиента найдёт ключ с recovery_point = order_created и продолжит с вызова провайдера. Второго списания не будет, потому что вызов провайдера тоже идемпотентен: ключ для него выводится из нашего ключа, а не генерируется заново. Это главное правило цепочки. Каждый следующий вызов получает ключ, однозначно выведенный из исходного, и тогда повтор на любом уровне безопасен

locked_at защищает от параллельной работы. Пока первый запрос держит ключ, повтор получает 409 Conflict, можно с Retry-After. Если процесс умер с захваченным ключом, блокировку считают протухшей через таймаут, и следующий повтор её забирает. Брандур описывает ещё два фоновых процесса: completer доводит до конца операции, которые клиент бросил повторять, а reaper удаляет старые ключи

Если внешний сервис не поддерживает ключи, перед повтором спрашивают у него статус операции по своему id. Если и этого нельзя, вызов уносят в outbox и честно принимают, что редкий дубль возможен: тогда его ловят сверкой

⚠️ Где ошибаются

  • Ключ проверяют в Redis, а заказ пишут в Postgres. Сервис записал ключ в Redis и упал до коммита заказа. Повтор видит ключ и отвечает «уже сделано», хотя заказа нет. Или наоборот: заказ создан, а ключ не записался. Ключ и изменение живут в одной базе и одной транзакции. Redis годится как быстрый замок перед ней, но не как единственная запись
  • Новый ключ на каждую попытку. Ключ генерируется в функции, которую вызывает цикл ретраев, или фронтенд создаёт его при каждом клике. Повторы приходят разными операциями. Ключ создают при намерении и хранят до ответа
  • Наружу уходит письмо до коммита. Обработчик отправил письмо, потом упал на сохранении ответа. Повтор выполнит всё снова, и клиент получит два письма. Побочные эффекты вне базы делают после коммита через outbox или с ключом на стороне получателя
  • Ключи хранят без области пользователя. Первичный ключ только по key. Два клиента с одинаковыми ключами получают ответы друг друга. Ключ всегда уникален в паре с владельцем

🎯 Вопросы с собеседований

Что такое идемпотентность и зачем она в микросервисах?

Операция идемпотентна, если повтор ничего не меняет. После двух одинаковых запросов система в том же состоянии, что после одного. В сети отправитель не отличает потерянный запрос от потерянного ответа, поэтому обязан повторять. Значит, получатель должен распознавать повторы. Вместе с доставкой at-least-once это даёт эффект ровно один раз

Пользователь нажал «Оплатить» пять раз. Как не списать деньги пять раз?

Блокировка кнопки до ответа спасает от двойного клика в одной вкладке, но не от второй вкладки и ретраев сети, поэтому нужна защита на сервере. Клиент при нажатии создаёт ключ идемпотентности и шлёт его со всеми попытками. Сервер первым делом вставляет ключ в таблицу с уникальным индексом в той же транзакции, что и платёж, и сохраняет ответ. Повторы получают сохранённый ответ, а параллельный повтор ждёт на индексе или получает 409

Где хранить ключи идемпотентности и сколько?

В той же базе, что и данные операции, чтобы ключ и изменение фиксировались одной транзакцией. Первичный ключ — пара из владельца и ключа, рядом хэш тела запроса и сохранённый ответ. Хранят дольше, чем клиент может повторять: у Stripe минимум сутки, Брандур Лич советует 72 часа. Старые строки удаляет фоновая задача по created_at

Что ответить на повтор, пока первый запрос ещё выполняется?

Нельзя выполнять его параллельно, иначе будет дубль. Если всё в одной транзакции, повтор сам подождёт на уникальном индексе и вернёт результат первого. Если операция долгая и ключ помечен как захваченный, сервер отвечает 409 Conflict, можно с Retry-After. Захват должен протухать по таймауту, иначе упавший процесс навсегда заблокирует ключ

Как сделать идемпотентной операцию, которая вызывает внешний платёжный сервис?

Внешний вызов нельзя положить в транзакцию базы, поэтому операцию делят на фазы: короткие транзакции до и после вызова, а в строке ключа хранят, какая фаза пройдена. Повтор продолжает с последней точки. Сам вызов провайдера делают с ключом, выведенным из нашего, например charge-<id ключа>, и провайдер сам отсечёт дубль. Если провайдер ключей не поддерживает, перед повтором запрашивают статус операции

Чем ключ идемпотентности отличается от уникального индекса на заказе?

Уникальный индекс по бизнес-ключу, например client_order_id, защищает от второй строки, но повтор получит ошибку unique violation, и её ещё надо превратить в правильный ответ. Ключ идемпотентности хранит ответ первого запроса и возвращает его, так что клиент не видит разницы между первым вызовом и повтором. Ещё он проверяет, что тело не поменялось. Если у сущности есть естественный ключ, часто хватает индекса и upsert

📚 Что почитать