Padrão Saga: como gerenciar transações distribuídas

O que é o padrão Saga?

Saga é um padrão para manter a consistência de um processo de negócio que atravessa vários serviços ou recursos transacionais.

Em vez de uma transação global com bloqueios compartilhados, o processo é dividido em operações locais, cada uma confirmada pelo participante responsável.

Quando uma etapa termina, uma mensagem, evento ou comando inicia a próxima. Se o objetivo deixa de ser alcançável, o sistema executa compensações para neutralizar efeitos anteriores.

A descrição do Azure Architecture Center apresenta a saga como uma sequência de transações locais, com compensações quando uma etapa falha.

O resultado é consistência eventual, não atomicidade instantânea entre todos os bancos. Durante o percurso, participantes podem observar estados intermediários.

Por isso, uma saga exige regras de domínio, estados explícitos e mecanismos de recuperação.

O problema das transações distribuídas

Em um monólito com um banco relacional, uma transação pode confirmar ou reverter várias alterações juntas.

Em uma arquitetura com banco por serviço, pedido, estoque, pagamento e logística controlam dados próprios. Nenhum serviço deveria abrir uma transação diretamente no banco do outro.

Protocolos de commit distribuído existem, mas podem ser indisponíveis, incompatíveis com alguns participantes ou inadequados para processos demorados.

Manter recursos bloqueados enquanto uma transportadora ou um operador humano responde por minutos é pouco prático.

O padrão Saga troca a atomicidade global por transações locais coordenadas e recuperação semântica.

Essa necessidade aparece principalmente em sistemas baseados em microsserviços, mas não depende deles.

Qualquer fluxo longo que combine bancos, APIs externas ou etapas humanas pode se beneficiar do mesmo raciocínio.

Como uma saga funciona

1. Uma solicitação cria uma instância da saga com identidade única.
2. O primeiro participante executa sua transação local.
3. O resultado confirmado aciona a próxima etapa.
4. O estado do fluxo registra quais ações foram concluídas.
5. Falhas transitórias são repetidas conforme uma política definida.
6. Falhas definitivas iniciam compensações das etapas aplicáveis.
7. A saga termina como concluída, compensada ou pendente de intervenção.

A saga deve persistir progresso suficiente para continuar depois de reinícios.

Guardar a sequência apenas na memória transforma uma queda do processo em perda do estado.

Mesmo na coreografia, cada participante precisa registrar o que processou e quais eventos produziu.

Exemplo de saga em um e-commerce

Etapa	Ação local	Compensação possível
Pedido	Criar pedido pendente	Cancelar pedido
Estoque	Reservar itens	Liberar reserva
Pagamento	Autorizar ou capturar valor	Cancelar autorização ou estornar
Entrega	Solicitar coleta	Cancelar solicitação, se ainda permitido

Se o pagamento for recusado, o sistema libera o estoque e cancela o pedido. Se a entrega falhar depois da captura, pode ser necessário estornar o pagamento, liberar itens e cancelar o pedido.

A ação correta depende do instante e das regras do negócio.

Uma falha técnica não deve ser confundida imediatamente com recusa. Se o provedor de pagamento não respondeu, o resultado pode ser desconhecido.

Antes de compensar, a saga consulta ou reconcilia o estado para não estornar uma cobrança que nunca ocorreu nem cobrar novamente.

Cada etapa é uma transação local

Cada participante protege suas próprias invariantes. O estoque reserva unidades em uma transação do serviço de estoque; pagamentos registra a autorização no banco de pagamentos.

A saga coordena resultados, mas não ignora os limites de propriedade dos dados.

A transação local deve salvar também a intenção de emitir o próximo evento de maneira confiável. Sem isso, o serviço pode confirmar o banco e falhar antes de avisar a continuação.

O Transactional Outbox é uma técnica comum para fechar essa janela, mantendo estado e evento no mesmo commit.

Compensação não é rollback

Um rollback de banco apaga uma alteração não confirmada como se ela nunca tivesse ocorrido. Uma compensação é uma nova transação de negócio executada depois que o efeito original já ficou visível.

Ela registra outro fato: uma reserva foi criada e depois liberada; um pagamento foi capturado e depois estornado.

Nem sempre é possível restaurar exatamente o passado. Taxas podem não ser devolvidas, câmbio pode variar, um cupom pode expirar e um e-mail não pode ser “desenviado”.

A compensação precisa produzir um resultado aceitável, preservar auditoria e, quando necessário, incluir atendimento humano.

Etapas compensáveis, pivô e repetíveis

• Compensáveis: podem receber uma ação semântica oposta, como liberar uma reserva.
• Pivô: representa um ponto de não retorno ou uma decisão após a qual a estratégia muda.
• Repetíveis: precisam continuar até o sucesso depois do pivô e, por isso, devem tolerar retentativas.

Essa classificação, também destacada na documentação da Microsoft, ajuda a ordenar o fluxo. Etapas irreversíveis devem ocorrer tarde, quando as validações e reservas compensáveis já foram concluídas.

Depois do pivô, o sistema normalmente busca conclusão para frente em vez de tentar desfazer tudo.

Saga por coreografia

Na coreografia, não existe um coordenador central do fluxo. Cada participante reage a eventos e publica o fato seguinte.

PedidoCriado pode acionar estoque; EstoqueReservado aciona pagamento; PagamentoRecusado aciona a liberação da reserva.

A orientação da AWS sobre saga por coreografia destaca o baixo acoplamento e a adequação a fluxos com poucos participantes. O modelo aproveita mensageria assíncrona e autonomia dos serviços.

• Pontos fortes: ausência de controlador central, serviços autônomos e adição simples de reações independentes.
• Riscos: fluxo espalhado entre consumidores, dependências implícitas, ciclos de eventos e dificuldade crescente de compreender quem inicia cada compensação.

Saga por orquestração

Na orquestração, um componente conhece o fluxo e envia comandos aos participantes. Ele registra o estado da instância, recebe os resultados e decide o próximo passo ou a compensação.

Os serviços continuam donos de suas transações locais; o orquestrador é dono da coordenação.

A documentação da AWS sobre orquestração descreve o coordenador central que administra o ciclo da transação distribuída. Essa centralização torna o fluxo mais visível, mas exige alta disponibilidade e impede que o orquestrador concentre regras internas que pertencem aos serviços.

• Pontos fortes: sequência explícita, estado central do workflow, testes mais diretos e compensações coordenadas.
• Riscos: dependência do orquestrador, crescimento excessivo da lógica e possível gargalo se a implementação não escalar.

Coreografia ou orquestração?

Critério	Coreografia	Orquestração
Controle do fluxo	Distribuído entre participantes	Explícito no orquestrador
Visibilidade	Exige correlacionar vários eventos	Estado concentrado no workflow
Acoplamento	A contratos e eventos observados	Participantes acoplados aos comandos do fluxo
Complexidade crescente	Interações podem virar uma rede difícil de seguir	Orquestrador pode acumular decisões demais
Melhor cenário	Poucos passos e reações naturais	Fluxos longos, ramificados ou regulados

Não transforme a escolha em regra religiosa. Uma jornada pode ter orquestração para o processo principal e eventos coreografados para analytics, notificações e outras reações que não controlam seu resultado.

O limite deve deixar claro quem decide o avanço e quem apenas observa.

Relação entre Saga e Transactional Outbox

Saga coordena uma transação de negócio entre participantes. Transactional Outbox garante que um participante não perca a mensagem que deveria publicar depois de confirmar seu banco.

Eles são complementares, não alternativas.

Sem outbox ou garantia equivalente, estoque pode reservar os itens e cair antes de emitir EstoqueReservado.

A saga fica parada, embora a transação local tenha ocorrido. Com outbox, a intenção de publicar é persistida junto à reserva e pode ser recuperada por polling ou Change Data Capture.

Idempotência é indispensável

Comandos, eventos e compensações podem chegar novamente. Um timeout não informa se o participante concluiu ou não.

A saga repete para recuperar, portanto “reservar estoque”, “capturar pagamento” e “liberar reserva” precisam reconhecer a identidade da operação.

Cada mensagem deve carregar saga_id, step_id e message_id. O participante registra o processamento na mesma transação do seu efeito local ou usa uma chave de negócio única.

A compensação também precisa ser idempotente: liberar duas vezes não pode aumentar o estoque indevidamente.

Isolamento e concorrência

Como não há isolamento global, duas sagas podem disputar o último item, alterar a mesma conta ou observar estados intermediários. Compensação não resolve automaticamente essas anomalias. Cada domínio precisa de mecanismos de concorrência compatíveis com suas invariantes.

• Reserva semântica: marcar o recurso como reservado antes da decisão final.
• Versão esperada: rejeitar atualização quando o estado mudou desde a leitura.
• Restrição única: impedir duas operações equivalentes no banco.
• Releitura: confirmar a condição imediatamente antes de uma etapa sensível.
• Comutatividade: projetar operações cuja ordem não altere o resultado quando possível.

Estado, correlação e ordenação

Uma saga durável registra etapa atual, passos concluídos, compensações registradas, tentativas, prazos e resultado final.

Esse estado permite retomar o fluxo e responder perguntas como “o pagamento foi autorizado?” ou “a liberação do estoque já terminou?”.

Propague correlation_id para ligar toda a jornada e causation_id para indicar qual mensagem causou a próxima.

Números de versão ajudam a ignorar respostas atrasadas. Um evento antigo não deve fazer uma saga compensada voltar para o estado em andamento.

Timeouts e retentativas

Timeout técnico não significa falha de negócio. Antes de compensar, classifique o erro: transitório, definitivo ou desconhecido.

Indisponibilidade temporária merece retentativa com espera progressiva e limite; cartão recusado é resultado definitivo; resposta perdida exige consulta ou reconciliação.

Defina prazo de cada etapa e prazo total do negócio. Quando o tempo expira, a saga precisa decidir entre continuar aguardando, consultar o participante, compensar ou encaminhar para análise humana. Não deixe instâncias pendentes indefinidamente.

E se a compensação falhar?

Compensações são chamadas distribuídas e podem falhar pelos mesmos motivos das etapas originais.

Elas devem ser duráveis, idempotentes e repetíveis. Registrar a compensação antes de iniciar uma ação sensível evita esquecer o que precisa ser corrigido após uma queda.

A documentação do padrão Saga no Temporal mostra a ideia de registrar ações compensatórias e executá-las quando uma etapa posterior falha.

Independentemente da ferramenta, uma falha permanente precisa de fila de intervenção, contexto suficiente e procedimento operacional seguro.

Observabilidade da saga

• quantidade de sagas em andamento, concluídas, compensadas e paradas;
• tempo total e duração por etapa;
• taxa de retentativas, timeouts e compensações;
• idade da instância pendente mais antiga;
• mensagens duplicadas, atrasadas ou fora de ordem;
• compensações que exigem intervenção manual.

Logs isolados de cada serviço não bastam. Propague identificadores e use OpenTelemetry para relacionar traces quando o desenho permitir. Uma estratégia de observabilidade deve mostrar o estado do negócio, não apenas CPU e disponibilidade dos processos.

Segurança e privacidade

Cada comando precisa autenticar o emissor técnico e autorizar a operação no contexto da saga. Não permita que um identificador previsível seja usado para cancelar ou consultar o processo de outra pessoa.

Assine mensagens quando atravessarem limites de confiança e aplique proteção equivalente em webhooks.

Evite copiar dados pessoais em todos os eventos. O estado do workflow deve armazenar o mínimo necessário, com criptografia, retenção e auditoria.

Compensações financeiras e administrativas merecem controles de autorização próprios; elas não são menos sensíveis por terem sido disparadas automaticamente.

Benefícios e limitações

Benefícios	Limitações
Respeita bancos independentes por serviço	Não oferece isolamento ACID global
Permite processos longos e assíncronos	Estados intermediários ficam visíveis
Recupera falhas por continuação ou compensação	Compensações adicionam regras e custo operacional
Escala participantes de forma independente	Mensagens duplicadas e atrasadas precisam ser tratadas
Modela decisões reais do negócio	Depuração é mais difícil que em uma transação local

Quando usar o padrão Saga

• o processo atravessa serviços ou bancos independentes;
• cada participante consegue confirmar uma transação local;
• há compensações ou uma estratégia de conclusão após o pivô;
• consistência eventual é aceitável;
• o fluxo pode durar além de uma requisição HTTP;
• falhas e intervenção precisam ser auditáveis.

Pedidos, viagens, onboarding, empréstimos, assinaturas e logística são candidatos comuns. A decisão começa pela jornada de negócio e suas invariantes, não pela quantidade de serviços.

Quando evitar

Não use Saga para substituir uma transação simples dentro do mesmo banco. Se o negócio exige isolamento forte e não tolera qualquer estado intermediário, talvez os limites dos serviços estejam incorretos ou outra estratégia transacional seja necessária.

Evite também quando não existe compensação aceitável nem caminho confiável para conclusão.

Nesse caso, o problema precisa ser redesenhado: reservar antes de confirmar, adiar a ação irreversível ou concentrar dados que precisam mudar atomicamente no mesmo limite.

Como implementar uma saga

1. Desenhe o resultado de negócio e os estados intermediários permitidos.
2. Liste participantes, transações locais e proprietários dos dados.
3. Defina compensações, etapa pivô e ações que devem ser repetidas até concluir.
4. Escolha coreografia ou orquestração conforme a complexidade do fluxo.
5. Crie contratos versionados com identidades de saga, etapa e mensagem.
6. Garanta publicação confiável por outbox ou mecanismo equivalente.
7. Torne comandos, eventos e compensações idempotentes.
8. Defina timeouts, retentativas, reconciliação e intervenção humana.
9. Persista o estado necessário para retomada.
10. Instrumente métricas e traces antes de colocar o fluxo em produção.

Para chamadas síncronas, aplique os mesmos cuidados dos contratos de API: erros claros, timeouts e identidade da operação. Processos longos geralmente funcionam melhor quando a API devolve um identificador e permite consultar o estado, em vez de manter a conexão aberta até o fim.

Como testar

• falha antes e depois de cada commit local;
• mensagem duplicada, atrasada e fora de ordem;
• timeout com resultado desconhecido no participante;
• queda do orquestrador e retomada em outra instância;
• falha durante cada compensação;
• duas sagas concorrendo pelo mesmo recurso;
• deploy com versões diferentes dos contratos;
• indisponibilidade prolongada do broker ou serviço;
• intervenção manual e posterior retomada;
• expiração do prazo total do negócio.

Valide o estado de todos os participantes, não apenas a resposta inicial. O teste termina quando a saga alcança um estado final coerente e auditável, inclusive depois de reinícios e retentativas.

Erros comuns

• Chamar compensação de rollback: esconde efeitos irreversíveis e auditoria.
• Compensar qualquer timeout: o resultado pode estar apenas desconhecido.
• Não persistir o estado: uma reinicialização perde o progresso.
• Ignorar duplicidade: retentativas passam a cobrar ou liberar duas vezes.
• Coreografar muitos participantes: o fluxo vira uma rede difícil de compreender.
• Criar um orquestrador onisciente: regras internas vazam dos serviços para o coordenador.
• Executar ação irreversível cedo: limita opções quando etapas posteriores falham.
• Não tratar compensação com falha: a saga fica parcialmente corrigida e invisível.
• Confundir consistência eventual com ausência de regras: invariantes continuam necessárias.

Perguntas frequentes

Saga substitui transações de banco?

Não. Cada etapa da saga continua usando uma transação local. O padrão coordena essas transações quando elas pertencem a participantes independentes.

O padrão Saga garante atomicidade?

Não de forma global e imediata. Ele busca um resultado consistente por etapas locais, continuação e compensação, enquanto estados intermediários podem ficar visíveis.

Coreografia ou orquestração: qual é melhor?

Depende do fluxo. Coreografia funciona bem com poucos participantes e reações naturais; orquestração favorece processos longos, ramificados e que exigem visibilidade central.

Uma compensação desfaz tudo exatamente?

Não necessariamente. Ela executa uma nova ação que neutraliza o efeito segundo o negócio. Estorno, cancelamento e liberação permanecem registrados no histórico.

Saga precisa usar mensageria?

Não obrigatoriamente, mas mensageria assíncrona favorece processos longos e desacoplados. Chamadas síncronas ainda exigem estado durável, idempotência, timeouts e recuperação.

Saga e Transactional Outbox são a mesma coisa?

Não. Saga coordena o processo entre serviços; outbox garante que cada serviço publique sua mensagem de forma confiável depois da transação local.

O que acontece se uma compensação falhar?

Ela deve ser repetida com segurança ou encaminhada para intervenção. A falha precisa permanecer visível e auditável até que o sistema alcance um estado final aceitável.

Conclusão

O padrão Saga permite coordenar processos distribuídos sem fingir que vários serviços compartilham uma única transação.

Ele combina commits locais, mensagens, retentativas e compensações para conduzir o negócio a um estado consistente.

A parte difícil não é escolher uma ferramenta, mas modelar o significado da falha: o que pode ser compensado, qual é o ponto de não retorno e quando concluir para frente.

Coreografia oferece autonomia em fluxos menores; orquestração torna jornadas complexas mais explícitas.

Em ambos os casos, publicação confiável, idempotência e observabilidade são requisitos de projeto, não detalhes posteriores.