Outbox Pattern

Garante que a persistência de dados e a publicação de mensagens ocorram atomicamente, sem depender de transações distribuídas. O serviço grava no banco de dados e na tabela outbox na mesma transação local; um relay separado publica as mensagens pendentes para o broker.

passos: 6
arquivos: 8
teste: 1
tecnologias: 5

Infraestrutura realTypeScriptBunPostgreSQLRedisDocker

Cenário Relações Comparar

Baixar cartão

Cenário

Um serviço de pagamentos grava o PIX e precisa avisar o serviço de notificação. Publicar no broker depois do INSERT é dual write: o processo cai entre os dois e o evento some. Com o Outbox, o evento entra na mesma transação do pagamento, e um relay separado o entrega a um Redis Stream — que, ao contrário do Pub/Sub, guarda o evento até o consumidor ler.

Como funciona

6 passos

Evento gravado na transação do dado.

Esconde cada passo: lembre antes de tocar para revelar.

Vocabulário compartilhado

XADD+3

FOR UPDATE SKIP LOCKED+2

SET NX EX+2

publishing+1

Outbox Pattern

claimed_at+1

Outbox Pattern

eventId+1

Outbox Pattern

01
paymentProcess grava o pagamento e a linha em outbox_messages (pending) na mesma transação
02
O relay reivindica um lote com FOR UPDATE SKIP LOCKED, gravando publishing e claimed_at — vários relays pegam lotes disjuntos
03
Publica cada evento no stream payment_events (XADD, com o eventId) e marca published
04
O reaper devolve a pending toda linha publishing com claimed_at além do lease — o relay que a reivindicou morreu antes de marcar
05
A entrega é at-least-onceO consumidor lê por consumer group e deduplica pelo eventId com SET NX EX antes de notificar
06
O demo simula o relay caindo depois de publicar: o evento sai de novo e o consumidor o reconhece como duplicado

apps/patterns/outbox-pattern

8 arquivos

sql/

01_schema.sqlschemaTabelas payments e outbox_messages (com claimed_at e índices parciais)

src/

service_payment.tspaymentProcess — pagamento e evento na mesma transação
relay_outbox.tsClaim com SKIP LOCKED, XADD no stream, marcação e reaper por lease
consumer_payment.tsConsumer group no stream com deduplicação por eventId
pool_bank.tstransactionExecute e conversão de centavos para NUMERIC
config_payment.tsLê e valida a configuração no boot
demo.tsdemoCria pagamentos, sobe relay e consumidor e simula a queda do relay
outbox_payment.test.tstesteIntegração com PostgreSQL e Redis reais: atomicidade, lotes disjuntos, lease e duplicata