Padrão saga e ações compensatórias

Pagamento capturado. Inventário reservado. Etiqueta de envio falhou — e o pedido fica em um estado que nenhum serviço possui. O padrão saga sequencia passos distribuídos com ações compensatórias: lógica explícita de desfazer que deve ser idempotente, ordenada e segura para executar mais de uma vez.

Engenharia9 min de leitura
Saga patternDistributed transactionsCompensating actionsEvent-drivenMicroservices
Compartilhar

O fluxo de checkout tocou três serviços. Pagamento autorizado. Inventário decrementado. API da transportadora deu timeout ao criar etiqueta. Pagamento ainda não estava capturado — mas inventário já mostrava quarenta unidades a menos. Suporte encontrou o pedido em PENDING_LABEL em nenhum runbook. SQL manual corrigiu uma linha; três webhooks de retry duplicados criaram mais dois pedidos parciais. O padrão saga com ações compensatórias existe porque não há COMMIT distribuído entre microsserviços de pagamento, inventário e envio — apenas transações locais, mensagens assíncronas e falha em qualquer passo. Sagas tornam explícitos processos de negócio multi-passo: passos forward avançam estado, falhas disparam passos compensatórios que desfazem semanticamente trabalho anterior, e cada handler assume entrega at-least-once.

Two-phase commit entre serviços heterogêneos é operacionalmente pesado — coordenadores, timeouts de lock, recuperação de falhas frágil. A maioria das equipes de produto o rejeita. Coreografia ingênua — "cada serviço escuta e reage" — esconde orquestração em cadeias de eventos implícitas que ninguém consegue rastrear quando o passo quatro falha. Sagas ocupam o meio: estado de processo visível, ordem de compensação definida, handlers idempotentes e aceitação de que consistência é eventual dentro de tempo limitado.

Coreografia vs orquestração: duas formas de saga

Ambas implementam a mesma ideia — sequência de transações locais com compensações — mas diferem no fluxo de controle.

Coreografia. Cada serviço completa seu passo e publica evento. Serviços downstream se inscrevem e agem. Compensação se propaga como eventos compensatórios em ordem inversa de dependência. Sem coordenador central.

OrderCreated → PaymentReserved → InventoryReserved → LabelFailed
  → InventoryReleased (compensate) → PaymentReleased (compensate) → OrderCancelled

Prós: acoplamento solto, sem single point of failure para lógica de orquestração. Contras: grafo implícito difícil de visualizar, ordem de compensação codificada em convenções de topics, debugging exige alfabetização em distributed trace.

Orquestração. Coordenador de saga (serviço state machine) emite comandos a participantes, rastreia passo atual e despacha compensações em falha. Participantes reportam sucesso ou falha; coordenador decide próximo passo forward ou backward.

Coordinator: RESERVE_PAYMENT → ok → RESERVE_INVENTORY → ok → CREATE_LABEL → fail
  → COMPENSATE_INVENTORY → COMPENSATE_PAYMENT → SAGA_FAILED

Prós: estado explícito, política de compensação centralizada, timeouts e escalação humana mais fáceis. Contras: disponibilidade do coordenador importa; pode virar god service se limites se difundem.

FactorChoreographyOrchestration
Contagem de passosPoucos, estáveisMuitos, ramificados
Topologia de equipeEquipes autônomas por serviçoPlatform possui fluxos transversais
Necessidades de visibilidadeFerramentas de trace fortesTabela de estado de saga integrada
Complexidade de compensaçãoEventos reversos simplesCompensação parcial condicional
Timeout / enforcement de SLATimers por serviçoDeadlines do coordenador

Nenhuma é universalmente correta. Checkout com cinco passos e impacto em receita costuma merecer orquestrador. Pipelines de notificação de dois serviços frequentemente sobrevivem com coreografia.

Ações compensatórias não são rollbacks

Rollback de banco desfaz transação antes do commit. Ações compensatórias desfazem efeitos de negócio já confirmados em outros serviços — semanticamente, não mecanicamente.

Forward stepNaive rollback (wrong)Compensating action (right)
Capturar pagamentoDELETE payment rowEmitir reembolso ou liberar hold de autorização
Reservar inventárioReverter transação se mesma DBLiberar reserva; restaurar contagem disponível
Enviar email de confirmaçãoImpossível desfazer envioEnviar email de correção; marcar saga failed
Criar envioDELETE se mesmo serviçoAnular etiqueta; cancelar solicitação de pickup
Publicar domain eventEsperar que ninguém consumiuEmitir evento compensatório; consumidores revertem

Compensações são operações de negócio com regras próprias. Reembolsar pagamento capturado pode levar três dias. Anular etiqueta pode falhar se transportadora já escaneou pacote. Lógica de compensação deve lidar com "desfazer impossível" — escalar para humano, compensação parcial ou aceitar estado residual com reconciliação.

Ação compensatória que assume que passo forward nunca teve sucesso parcial corromperá estado em retry.

Projetar compensações idempotentes desde o dia um — mesmos padrões de upserts idempotentes em Postgres: dedup key por comando de compensação, unique constraint em (saga_id, step, direction), upsert de status de compensação para mensagens duplicadas não reembolsarem duas vezes.

Estado de saga e outbox em cada passo

Cada passo forward e compensatório deve ser uma transação local: atualizar estado de domínio, registrar progresso de saga, emitir próximo comando ou evento.

BEGIN;
  UPDATE inventory
  SET reserved = reserved - $qty, available = available + $qty
  WHERE sku = $1 AND order_id = $2;
 
  INSERT INTO saga_step_log (saga_id, step, direction, status, idempotency_key)
  VALUES ($saga_id, 'release_inventory', 'compensate', 'completed', $key)
  ON CONFLICT (idempotency_key) DO NOTHING;
 
  INSERT INTO outbox (aggregate_id, event_type, payload)
  VALUES ($saga_id, 'InventoryReleased', $payload);
COMMIT;

O padrão transactional outbox garante que eventos de compensação sobrevivam crash de processo — crítico porque falha frequentemente dispara compensação durante instabilidade. Publicar eventos de compensação fora da transação recria o dual-write gap no pior momento.

Opções de armazenamento de estado de saga:

Tabela de coordenador. saga_instances(id, type, current_step, status, context_json, updated_at) — orquestrador lê e escreve.

Event log. Eventos de saga append-only; projector constrói estado atual — alinhado com event sourcing em granularidade de saga.

Log de participação por serviço. Cada serviço registra seu passo para um saga_id — modelo de coreografia; reconciliação une logs.

Valores de status precisam de precisão: RUNNING, COMPENSATING, COMPLETED, FAILED, COMPENSATION_FAILED (requer humano). COMPENSATION_FAILED não é opcional em sistemas maduros — algumas rotas de desfazer falham.

Ordenar compensação: reverso, parcial e passos pivot

Quando passo N falha, compensar N-1, N-2, … até passos forward completados. Ordem importa quando compensação downstream depende de liberação upstream — liberar inventário antes de reembolsar pagamento se reembolso dispara reordem automática que re-reserva estoque.

Regra de ordem inversa. Compensar em ordem inversa de conclusão de passos forward. Se pagamento e inventário tiveram sucesso, inventário tipicamente compensa primeiro (restaurar estoque) antes de pagamento (liberar fundos) — dependente do domínio, documentar por tipo de saga.

Progresso forward parcial. Passo três falha; passos um e dois confirmados. Compensar dois, depois um — nunca pular porque passo três nunca começou.

Passos não compensáveis. Email enviado, API externa chamada sem endpoint de void. Saga marca COMPLETED_WITH_IRREVERSIBLE_SIDE_EFFECT, dispara workflow humano, não finge rollback completo. Projetar passos forward compensáveis — atrasar envio até commit de saga — é escolha arquitetural.

Pivot / retry vs compensate. Timeout transitório da transportadora pode reintentar criação de etiqueta três vezes antes de compensar inventário. Coordenador distingue falhas reintentáveis (mesmo passo, backoff) de falhas terminais (cadeia de compensação). Difundir os dois causa reembolsos prematuros ou loops infinitos de retry.

Forward:  S1 ──► S2 ──► S3 (fail terminal)
Compensate:      ◄── C2 ◄── C1

Timeouts, obsolescência e garbage collection de saga

Sagas de longa duração estagnam quando participante nunca responde. Sem timeouts, inventário fica reservado indefinidamente.

Deadline por passo. Coordenador agenda evento de timeout; ao disparar, tratar como falha e compensar passos completados — ou escalar se compensação for arriscada.

TTL de saga. Sagas em RUNNING por mais tempo que SLA de negócio (ex.: 24 horas para checkout) falham automaticamente e compensam. Alertar antes de auto-ação quando possível.

Compensação obsoleta. Mensagem de compensação chega após retry forward ter sucesso — corrida clássica. Contadores de versão em instância de saga: ignorar compensação para step_version substituído por retry bem-sucedido. saga_epoch monotônico por instância.

Retry forward idempotente. Passo três falha transitivamente; retry não deve re-executar efeitos colaterais da tentativa parcial do passo três. Usar idempotency keys em APIs externas; checar log de participação antes de chamar carrier create duas vezes.

Testing e observabilidade para correção de saga

Sagas falham em produção de formas que unit tests não capturam: entrega duplicada, corrida compensação-antes-forward, sucesso externo parcial.

Matriz de test.

ScenarioExpected outcome
Todos os passos têm sucessoCOMPLETED, sem compensação
Passo k falha terminalPassos 1..k-1 compensados, FAILED
Comando forward duplicadoUm único efeito colateral
Compensação duplicadaUm único undo
Crash após commit forward, antes de outboxRelay entrega; sem double forward
Compensação falhaCOMPENSATION_FAILED, alerta

Tracing. Propagar saga_id e step em cada linha de log, header de mensagem e atributo de span. Dashboards: sagas por status, tempo médio de conclusão, taxa de compensação, sagas presas além do deadline.

Jobs de reconciliação. Nightly comparar capturas de pagamento com reservas de inventário e etiquetas enviadas — sagas curam drift que automação perde.

Limites de saga e quando não usar o padrão

Nem toda interação multi-serviço é saga. Read paths que agregam dados de três APIs — saga não necessária. Escrita forward única com notificação async — outbox mais consumidor idempotente basta. Reservar complexidade de saga para workflows onde múltiplos passos confirmados devem ser desfeitos como unidade quando passos posteriores falham.

Sinais de que sagas valem o custo:

  • Impacto em receita ou inventário se ficar em estado parcial durante a noite
  • Parceiros externos (pagamento, envio, ERP) cada um com modos de falha independentes
  • Processo visível ao usuário que abrange minutos a horas (onboarding, provisioning, fulfillment)
  • Requisito regulatório de provar audit trail de passos forward e compensatórios

Sinais para simplificar:

  • Dois serviços, um evento, compensação é "deletar linha que acabamos de inserir"
  • Falha aceitável como fila de limpeza manual revisada semanalmente
  • Todos os passos compartilham um banco — usar transação local

Sobre-saga-ing cria gargalos de coordenador e cadeias de compensação para fluxos que um único BEGIN…COMMIT resolveria. Sub-saga-ing deixa estado parcial como conhecimento tribal em macros de suporte.

Como equipes devem implementar sagas com ações compensatórias?

Escolhas de implementação que previnem incidentes com forma de saga.

Quando coreografia basta?

Dois a três serviços, fluxo linear, compensações são reversões simples de eventos, equipe compartilha rotação on-call. Adicionar orquestração quando ramificação aparece, SLAs endurecem ou compensação exige lógica condicional.

Quão granulares devem ser passos de saga?

Um passo com significado de negócio por transação local — não um por sentença SQL, não checkout inteiro em um passo. Passos mais finos aumentam precisão de compensação; passos mais grossos simplificam coordenação mas ampliam blast radius de falha parcial.

Compensações devem chamar APIs externas de forma síncrona?

Preferir comandos de compensação async com handlers idempotentes — igual a passos forward. Compensação síncrona na thread de request HTTP acopla latência de usuário à disponibilidade de API de void da transportadora.

Como sagas se relacionam com two-phase commit?

Sagas trocam atomicidade por disponibilidade e simplicidade. Aceitar inconsistência temporária (inventário liberado, reembolso pendente) com status claro e reconciliação. Não simular 2PC com locks entre serviços.

Um argumento comum vai na outra direção

A postura oposta sustenta que sagas superengenheiram o que retries e handlers idempotentes resolvem — "só tornar cada handler idempotente e deixar message broker redeliver."

Idempotência previne efeitos forward duplicados; não define o que acontece quando passo três falha após passos um e dois confirmados. Sem ações compensatórias, sagas falhas deixam recursos reservados, pagamentos retidos e pedidos órfãos — retry idempotente do passo três não libera inventário em falha terminal. Retries abordam erros transitórios; compensações abordam falha terminal e undo semântico. Ambos são necessários.

Key takeaways

  • Processos de negócio distribuídos precisam de coordenação explícita de saga — cadeias de eventos implícitas escondem ownership de falha.
  • Ações compensatórias são undos de negócio idempotentes, não rollbacks de banco — projetar para falha parcial e passos irreversíveis.
  • Cada passo confirma localmente com eventos emitidos por outbox — mudança de estado atômica e intenção de mensagem.
  • Compensar em ordem inversa de passos forward completados; distinguir falhas reintentáveis de terminais.
  • Timeouts, TTL de saga e guards de versão previnem compensação presa e em corrida.
  • Orquestração encaixa em ramificação complexa; coreografia em fluxos lineares curtos com tracing forte.
  • Testar entrega duplicada, timing de crash e falha de compensação — não apenas happy path.

Conclusion

O padrão saga torna falha distribuída input de design de primeira classe. Passos forward avançam processo de negócio; ações compensatórias restauram invariantes quando passo falha terminalmente; estado de saga torna progresso visível em vez de espalhado em logs de serviços.

Equipes que entregam workflows multi-serviço sem caminhos de compensação documentados devem mapear um fluxo crítico — identificar passos forward, escrever ação compensatória por passo, adicionar idempotency keys, conectar outbox em cada limite. O primeiro drill expõe quantas suposições de "rollback" são na verdade tickets manuais de suporte.

Artigos relacionados

Paleta de comandos

Pesquise um comando para executar...