Шпаргалка · Архитектура
Транзакционный outbox
Проблема
Магазин сохраняет покупку в свою базу, а затем публикует событие, чтобы сервис лояльности начислил баллы. Две записи в две системы без общей транзакции: время от времени commit проходит, а publish нет, и баллы просто исчезают. Outbox пишет событие в ту же базу в той же транзакции, relay доставляет его хотя бы один раз, потребитель отбрасывает дубли, а ключи, очистка и чтение лога закрывают остальное.
Чему вы научитесь
- Почему «сначала commit, потом publish» теряет события в любом порядке и как таблица outbox в той же транзакции закрывает эту дыру
- Как relay читает outbox через
FOR UPDATE SKIP LOCKEDи почему он может обещать только доставку at-least-once - Идемпотентность потребителя: таблица обработанных событий, которая коммитится вместе с эффектом
- Порядок внутри агрегата через ключ сообщения, очистка отправленных строк и выбор между polling и чтением лога базы
Диаграмма как код
Итоговая схема урока в виде текста: вставьте её в 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_brokerMermaid: последовательность запросов
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_slotD2
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
@endumlPlantUML: компоненты
@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 до publish | 4 мс | 40 мс |
| Неотправленные строки outbox | 0 | 0 |
| Строк в outbox | 0 | 900 000 |
Шаги
- Кейс Сохранить покупку, потом сообщить всем
Сервис покупок коммитит покупку в свою базу.
- Проблема Commit проходит, publish нет
В 21:14 брокер тормозит.
- Решение Записать событие в ту же транзакцию
Сервис перестаёт обращаться к брокеру.
- Решение Relay публикует содержимое outbox
Небольшой воркер, relay, каждые 500 мс читает неотправленные строки, публикует их, ждёт ack от брокера и помечает строки отправленными.
- Проблема Relay перезапускается, баллы начисляются дважды
Под relay убивают между публикацией и пометкой.
- Решение Потребитель помнит, что уже применил
Сервис лояльности записывает каждый
event_idвprocessed_eventsв той же транзакции, что и начисление. - Проблема Возврат приходит раньше покупки
Ради пропускной способности добавляют второй под relay.
- Решение Один ключ на покупку, одна партиция на ключ
Relay ставит ключом сообщения id покупки, а каждый под relay берёт только ключи, чей хеш попадает в его долю.
- Проблема Outbox хранит каждое событие вечно
Отправленные строки никто не удаляет.
- Решение Удалять отправленные строки маленькими пачками
Отдельная задача раз в минуту удаляет строки, отправленные больше 3 дней назад, по 5 000 за раз.
- Решение Или читать outbox из лога базы
Вместо опроса relay может следить за write-ahead log базы через слот репликации, как это делает CDC.
- Итоги Итог
Шесть правил outbox.
Термины
- Outbox relay
- Воркер, который читает неотправленные строки таблицы outbox, публикует их в брокер и помечает отправленными после ack. Если он упадёт до пометки, строки уйдут снова, поэтому доставка получается at-least-once.
- Таблица inbox (processed events)
- Таблица, куда потребитель пишет id каждого применённого события с уникальным ключом в той же транзакции, что и эффект. Повторная доставка упирается в ключ и пропускается.
- Ключ сообщения (partition key)
- Значение, по которому брокер выбирает партицию для сообщения, обычно id агрегата. Сообщения с одним ключом попадают в одну партицию и сохраняют порядок; между разными ключами порядок не гарантирован.
- Версия агрегата
- Порядковый номер события внутри своего агрегата: 1, 2, 3. Потребитель хранит последнюю применённую версию, более старую отбрасывает, а при пропуске ждёт предыдущую.