mufassall

Шпаргалка · Архитектура

Транзакционный outbox

14 мин · Продвинутый · mufassall.dtwin.uz/ru/l/outbox-pattern/

← Открыть урок

Проблема

Магазин сохраняет покупку в свою базу, а затем публикует событие, чтобы сервис лояльности начислил баллы. Две записи в две системы без общей транзакции: время от времени commit проходит, а publish нет, и баллы просто исчезают. Outbox пишет событие в ту же базу в той же транзакции, relay доставляет его хотя бы один раз, потребитель отбрасывает дубли, а ключи, очистка и чтение лога закрывают остальное.

Чему вы научитесь

  • Почему «сначала commit, потом publish» теряет события в любом порядке и как таблица outbox в той же транзакции закрывает эту дыру
  • Как relay читает outbox через FOR UPDATE SKIP LOCKED и почему он может обещать только доставку at-least-once
  • Идемпотентность потребителя: таблица обработанных событий, которая коммитится вместе с эффектом
  • Порядок внутри агрегата через ключ сообщения, очистка отправленных строк и выбор между polling и чтением лога базы
Итоговая сцена
70%

Диаграмма как код

Итоговая схема урока в виде текста: вставьте её в Jira, GitLab, GitHub, Notion или документацию, там Mermaid рисуется сам. Есть варианты для D2 и PlantUML (Confluence, IntelliJ).

Mermaid: схема

flowchart LR
  n_app(["Приложение магазина"])
  n_api["Сервис покупок"]
  n_db[("БД покупок")]
  n_broker[["Брокер"]]
  n_loyalty["Сервис лояльности"]
  n_ldb[("БД лояльности")]
  n_relay("Outbox relay")
  n_app -->|"вызов"| n_api
  n_api --> n_db
  n_broker -->|"асинхронно"| n_loyalty
  n_loyalty --> n_ldb
  n_relay --> n_db
  n_relay -->|"асинхронно"| n_broker

Mermaid: последовательность запросов

sequenceDiagram
  participant n_api as Сервис покупок
  participant n_broker as Брокер
  participant n_db as БД покупок
  participant n_relay as Outbox relay
  participant n_loyalty as Сервис лояльности
  participant n_ldb as БД лояльности
  Note over n_api,n_broker: Сохранить покупку, потом сообщить всем
  n_api->>n_broker: POST /v1/purchases -#62; purchase p_9051
  Note over n_api,n_broker: Commit проходит, publish нет
  n_api->>n_broker: 21:14:07.120 p_9188 COMMIT ok
  Note over n_api,n_db: Записать событие в ту же транзакцию
  n_api->>n_db: BEGIN#59;
  n_db-->>n_api: COMMIT 3 ms (both rows or none)
  Note over n_relay,n_db: Relay публикует содержимое outbox
  n_relay->>n_db: SELECT id, aggregate_id, type, payload FROM outbox
  Note over n_broker,n_loyalty: Relay перезапускается, баллы начисляются дважды
  n_broker->>n_loyalty: 21:30:01 loyalty evt_01HV9Q PurchaseCompleted p_9188 +249 points
  Note over n_loyalty,n_ldb: Потребитель помнит, что уже применил
  n_loyalty->>n_ldb: BEGIN#59;
  n_ldb-->>n_loyalty: INSERT 0 0 -#62; duplicate, skipped
  Note over n_broker,n_loyalty: Возврат приходит раньше покупки
  n_broker->>n_loyalty: partition 3 offset 88120 PurchaseRefunded p_9188
  Note over n_relay,n_broker: Один ключ на покупку, одна партиция на ключ
  n_relay->>n_broker: produce topic=purchase-events
  n_broker-->>n_relay: ack partition 3 offset 88121
  Note over n_relay,n_db: Outbox хранит каждое событие вечно
  n_relay->>n_db: EXPLAIN ANALYZE SELECT ... FROM outbox WHERE sent_at IS NULL LIMIT 200#59;
  n_db-->>n_relay: Index Scan using outbox_unsent (rows=200)
  Note over n_relay,n_db: Удалять отправленные строки маленькими пачками
  n_relay->>n_db: DELETE FROM outbox
  n_db-->>n_relay: DELETE 5000
  Note over n_relay,n_db: Или читать outbox из лога базы
  n_relay->>n_db: relay mode=log slot outbox_slot

D2

direction: right

n_app: "Приложение магазина" {
  shape: rectangle
}
n_api: "Сервис покупок" {
  shape: rectangle
}
n_db: "БД покупок" {
  shape: cylinder
}
n_broker: "Брокер" {
  shape: queue
}
n_loyalty: "Сервис лояльности" {
  shape: rectangle
}
n_ldb: "БД лояльности" {
  shape: cylinder
}
n_relay: "Outbox relay" {
  shape: rectangle
  style.multiple: true
}

n_app -> n_api: "вызов"
n_api -> n_db
n_broker -> n_loyalty: "асинхронно"
n_loyalty -> n_ldb
n_relay -> n_db
n_relay -> n_broker: "асинхронно"

PlantUML: последовательность запросов

@startuml
participant "Сервис покупок" as n_api
queue "Брокер" as n_broker
database "БД покупок" as n_db
participant "Outbox relay" as n_relay
participant "Сервис лояльности" as n_loyalty
database "БД лояльности" as n_ldb
note over n_api, n_broker : Сохранить покупку, потом сообщить всем
n_api ->> n_broker : POST /v1/purchases -> purchase p_9051
note over n_api, n_broker : Commit проходит, publish нет
n_api ->> n_broker : 21:14:07.120 p_9188 COMMIT ok
note over n_api, n_db : Записать событие в ту же транзакцию
n_api -> n_db : BEGIN;
n_db --> n_api : COMMIT 3 ms (both rows or none)
note over n_relay, n_db : Relay публикует содержимое outbox
n_relay -> n_db : SELECT id, aggregate_id, type, payload FROM outbox
note over n_broker, n_loyalty : Relay перезапускается, баллы начисляются дважды
n_broker ->> n_loyalty : [дубль] 21:30:01 loyalty evt_01HV9Q PurchaseCompleted p_9188 +249 points
note over n_loyalty, n_ldb : Потребитель помнит, что уже применил
n_loyalty -> n_ldb : BEGIN;
n_ldb --> n_loyalty : INSERT 0 0 -> duplicate, skipped
note over n_broker, n_loyalty : Возврат приходит раньше покупки
n_broker ->> n_loyalty : partition 3 offset 88120 PurchaseRefunded p_9188
note over n_relay, n_broker : Один ключ на покупку, одна партиция на ключ
n_relay ->> n_broker : produce topic=purchase-events
n_broker -->> n_relay : ack partition 3 offset 88121
note over n_relay, n_db : Outbox хранит каждое событие вечно
n_relay -> n_db : EXPLAIN ANALYZE SELECT ... FROM outbox WHERE sent_at IS NULL LIMIT 200;
n_db --> n_relay : Index Scan using outbox_unsent (rows=200)
note over n_relay, n_db : Удалять отправленные строки маленькими пачками
n_relay -> n_db : DELETE FROM outbox
n_db --> n_relay : DELETE 5000
note over n_relay, n_db : Или читать outbox из лога базы
n_relay -> n_db : relay mode=log slot outbox_slot
@enduml

PlantUML: компоненты

@startuml
left to right direction
agent "Приложение магазина" as n_app
component "Сервис покупок" as n_api
database "БД покупок" as n_db
queue "Брокер" as n_broker
component "Сервис лояльности" as n_loyalty
database "БД лояльности" as n_ldb
collections "Outbox relay" as n_relay
n_app --> n_api : вызов
n_api --> n_db
n_broker --> n_loyalty : асинхронно
n_loyalty --> n_ldb
n_relay --> n_db
n_relay --> n_broker : асинхронно
@enduml

Итог

Шесть правил outbox.

1) Никогда не пишите в базу и в брокер двумя шагами: в любом порядке события либо теряются, либо выдумываются. 2) Вставляйте событие в таблицу outbox в той же транзакции, что и данные. 3) Relay публикует неотправленные строки и помечает их после ack; это at-least-once, никогда не exactly-once. 4) Потребители дедуплицируют по id события в той же транзакции, что и эффект. 5) Ставьте ключом сообщения id агрегата и делите relay по ключу, тогда события одного агрегата идут по порядку. 6) Удаляйте отправленные строки или сбрасывайте партиции; опрос выбирайте ради простоты, чтение лога ради низкой задержки.

Показатели: в начале и в конце

ПоказательВ началеВ конце
Потерянные события0/день0/день
Двойные начисления0/день0/день
События не по порядку0/день0/день
От commit до publish4 мс40 мс
Неотправленные строки outbox00
Строк в outbox0900 000

Шаги

  1. Кейс Сохранить покупку, потом сообщить всем

    Сервис покупок коммитит покупку в свою базу.

  2. Проблема Commit проходит, publish нет

    В 21:14 брокер тормозит.

  3. Решение Записать событие в ту же транзакцию

    Сервис перестаёт обращаться к брокеру.

  4. Решение Relay публикует содержимое outbox

    Небольшой воркер, relay, каждые 500 мс читает неотправленные строки, публикует их, ждёт ack от брокера и помечает строки отправленными.

  5. Проблема Relay перезапускается, баллы начисляются дважды

    Под relay убивают между публикацией и пометкой.

  6. Решение Потребитель помнит, что уже применил

    Сервис лояльности записывает каждый event_id в processed_events в той же транзакции, что и начисление.

  7. Проблема Возврат приходит раньше покупки

    Ради пропускной способности добавляют второй под relay.

  8. Решение Один ключ на покупку, одна партиция на ключ

    Relay ставит ключом сообщения id покупки, а каждый под relay берёт только ключи, чей хеш попадает в его долю.

  9. Проблема Outbox хранит каждое событие вечно

    Отправленные строки никто не удаляет.

  10. Решение Удалять отправленные строки маленькими пачками

    Отдельная задача раз в минуту удаляет строки, отправленные больше 3 дней назад, по 5 000 за раз.

  11. Решение Или читать outbox из лога базы

    Вместо опроса relay может следить за write-ahead log базы через слот репликации, как это делает CDC.

  12. Итоги Итог

    Шесть правил outbox.

Термины

Outbox relay
Воркер, который читает неотправленные строки таблицы outbox, публикует их в брокер и помечает отправленными после ack. Если он упадёт до пометки, строки уйдут снова, поэтому доставка получается at-least-once.
Таблица inbox (processed events)
Таблица, куда потребитель пишет id каждого применённого события с уникальным ключом в той же транзакции, что и эффект. Повторная доставка упирается в ключ и пропускается.
Ключ сообщения (partition key)
Значение, по которому брокер выбирает партицию для сообщения, обычно id агрегата. Сообщения с одним ключом попадают в одну партицию и сохраняют порядок; между разными ключами порядок не гарантирован.
Версия агрегата
Порядковый номер события внутри своего агрегата: 1, 2, 3. Потребитель хранит последнюю применённую версию, более старую отбрасывает, а при пропуске ждёт предыдущую.