Implementando idempotência e padrões inbox em arquiteturas event-driven
Neste texto, aprofundo o uso de padrões inbox e idempotência para assegurar o processamento único de eventos em arquiteturas event-driven, com foco prático na implementação em .NET e integração a testes robustos.

Para aplicações event-driven, um desafio recorrente é garantir que eventos sejam processados exatamente uma vez, mesmo diante de reenvios causados por falhas ou timeouts. Este artigo aprofunda um ponto importante do meu post sobre estratégias para migração gradual de monólitos para microsserviços estratégias para migração gradual: a implementação de padrões inbox para garantir a idempotência no consumo dos eventos.
Em um sistema que adota arquitetura orientada a eventos, um job responsável por processar mensagens consumidas de um broker começou a apresentar comportamentos indesejados no sistema, como criação duplicada de registros e inconsistências de estado decorrentes do reprocessamento do mesmo evento. Os logs evidenciaram múltiplos processamentos do mesmo evento, indicando reenvios ocasionais, um cenário comum devido a confirmações que não chegam a tempo ou falhas transitórias na rede.
Hipóteses iniciais falsas
Supondo que o broker garantiria o processamento único: Em projetos que usei como o sistema de comércio exterior, precisamos lembrar que brokers como RabbitMQ, embora ofereçam mecanismos de ack, são sujeitos a reentregas em caso de falhas, justamente para garantir entrega ao menos uma vez, não exatamente uma vez. Isso exige tratamento explícito do lado consumidor.
Confiança na lógica de negócio para evitar duplicados: Sem uma camada técnica dedicada, a prevenção se mostrou frágil e difícil de manter, já que a complexidade crescia à medida que mais eventos transitavam entre contextos.
Investigação e causa raiz
A raiz do problema estava em não aplicar um padrão robusto para garantir idempotência. Minha experiência mostra que o padrão conhecido como inbox pattern é uma solução prática e testada para isso. Consiste basicamente em registrar, numa tabela própria na mesma transação do processamento do evento, um identificador único do evento consumido (normalmente o event ID ou a chave natural da mensagem). Antes de processar um evento, verifica-se esta tabela. Se o evento já foi consumido, o processamento é ignorado, pois a presença do evento na tabela inbox garante que suas ações já foram aplicadas, evitando assim efeitos colaterais duplicados; caso contrário, o processamento ocorre normalmente e o evento é marcado como processado.
Por que isso é necessário? Porque o banco de dados e o broker não compartilham transação distribuída (2PC) o que está alinhado com o problema conhecido descrito no padrão Transactional outbox, que consiste em registrar as mensagens a serem enviadas numa tabela da base de dados dentro da mesma transação das operações de escrita, garantindo que o disparo do evento fique sincronizado com o estado do banco e evitando inconsistências entre o sistema e o broker. microservices.io. Dependendo do cenário, o evento pode ser recebido múltiplas vezes, mas aplicar o padrão inbox impede efeitos colaterais repetidos.
Implementação prática no backend .NET
No .NET 10, utilizando EF Core, que é o ORM (Object-Relational Mapper) da Microsoft para .NET responsável por facilitar o acesso e manipulação de dados em bancos relacionais como o PostgreSQL, a recomendação é a seguinte::
Tabela InboxMessage: armazena os IDs dos eventos que já foram processados. Idealmente, o schema é minimalista, com uma chave única no event_id, timestamps para monitoramento e flags para auditoria.
Transação com atomicidade garantida ao processamento do evento: atomicidade significa que todas as operações dentro da transação ocorrem de forma completa ou nenhuma ocorre, evitando efeitos parciais em caso de falhas. Ao consumir o evento, dentro da mesma transação do EF Core, insere-se o registro na tabela inbox. Caso o registro exista (a inserção falhe por chave duplicada), o processamento subsequente é simplesmente ignorado, garantindo que o evento seja processado uma única vez.
Tratamento de exceções e retries: o padrão inbox permite que, se ocorrer falha após o commit da transação, o evento pode ser reenviado sem duplicação.
Exemplo ilustrativo (não copiado de projeto direto):
public async Task ProcessEventAsync(EventMessage (objeto que contém os dados do evento recebido para processamento) eventMessage, CancellationToken (token para controle de cancelamento da operação assíncrona) ct)
{
using var transaction = await dbContext.Database.BeginTransactionAsync(ct);
var alreadyProcessed = await dbContext.InboxMessages
.AnyAsync(im => im.EventId == eventMessage.Id, ct);
if (alreadyProcessed)
{
return; // Salva idempotencia
}
// Lógica principal do processamento do evento
await HandleBusinessLogicAsync(eventMessage, ct);
// Marca evento como processado no inbox
dbContext.InboxMessages.Add(new InboxMessage { EventId = eventMessage.Id, ProcessedAt = DateTime.UtcNow });
await dbContext.SaveChangesAsync(ct);
await transaction.CommitAsync(ct);
}
Integração com testes robustos
Na minha prática, especialmente em sistemas como LeadsMap, uma ferramenta de prospecção B2B outbound com workflows complexos, e o sistema de comércio exterior, que gerencia processos administrativos e financeiros multilocatários, testes de integração envolvem o uso de WebApplicationFactory montando a API inteira, usando Testcontainers para iniciar bancos PostgreSQL (ou MongoDB quando aplicável) e substituindo Keycloak por TestAuthHandler. Para a camada inbox, cubro cenários como:
- Processamento repetido do mesmo evento não altera o estado além da primeira vez.
- Inserção correta na tabela inbox.
- Resiliência a falhas simuladas entre etapas do processamento.
Essa abordagem de testes aumentou significativamente a estabilidade em produção, refletida na redução de incidentes relacionados a processamentos duplicados e na melhora da cobertura de cenários críticos de idempotência, com centenas de casos de integração validando o comportamento esperado antes de cada deploy.
Análise dos trade-offs e limitações
O padrão inbox implica:
- Esforço adicional para manter e monitorar a tabela inbox, que cresce conforme o volume de eventos.
- Risco de latência no processamento, já que a checagem e inserção no banco são necessárias para cada evento.
- Possível acúmulo de dados antigos, que exijo políticas de expurgo compatíveis com a retenção do sistema.
Também, é importante lembrar que o padrão inbox não substitui mecanismos de confiabilidade do broker, ele complementa, garantindo o processamento único no lado consumidor.
Guarda contra repetir o defeito e o que não cobre
Na prática, após implementar o padrão inbox, adotei políticas de monitoração para eventuais falhas na inserção do registro (exceções no banco, deadlocks) e alertas para latência ou crescimento anormal na tabela. Também implementei retries idempotentes na chamada do processo, sempre ciente que retries de commit podem acontecer.
No entanto, esse padrão não assegura consistência distribuída forte nem garante que todas as reações a eventos externos estejam sincronizadas, essas são limitações inerentes ao modelo eventual consistente em event-driven architectures. Para migrações ou cenários com domínios altamente sensíveis, outras abordagens podem ser necessárias, como sagas (orquestrações de processos distribuídos), ou transações compensatórias (ações para desfazer efeitos de processos anteriores), que são tópicos avançados e ficam fora do escopo deste artigo.
Referências
- Estratégias para migração gradual de monólitos para microsserviços usando Event-Driven Architecture: contexto e arquitetura event-driven aplicada em migrações.
- Pattern: Transactional outbox: explicação do padrão inbox para garantir atomicidade entre DB e mensagens.
- Idempotent requests | Stripe API Reference: visão prática sobre idempotência em APIs HTTP.
Receba o resumo da semana
Um e-mail por semana com o que foi publicado. Sem spam, e você sai quando quiser.
Continue lendo
- Do e-mail copiado à mão ao funil num sistema só: cinco decisões e o que cada uma custouUma empresa de comércio exterior, que conduz processos de mudança para os clientes, recebia os pedidos de orçamento por e-mail, enviados por três plataformas de geração de leads. Alguém lia cada mensagem e copiava os dados à mão. Este texto conta cinco decisões que tomei ao construir o sistema que substituiu esse trabalho, e o que cada uma deixou pior.
- Governança e monitoramento de eventos para evitar inconsistências em microsserviçosGerenciar eventos em microsserviços requer governança e monitoramento detalhados para evitar inconsistências como perda e duplicação. Compartilho práticas de auditoria automatizada, dashboards e alertas baseados em minha experiência com sistemas event-driven.
- Event-driven interno: desacoplamento por eventos locais em monólitos moduladosEste texto aprofunda um ponto do post sobre migração gradual de monólitos para microsserviços via event-driven architecture, detalhando como adotar eventos locais dentro do próprio monólito pode ajudar no desacoplamento entre módulos, simplificando evolução e testes.