Outbox Pattern na Prática: Mensageria Confiável em um Banco Digital (Portuguese)

José Marcos — Tue, 04 Nov 2025 02:20:42 +0000

Quando falamos de sistemas financeiros, confiabilidade não é um luxo, é um requisito.
Uma transferência bancária não pode simplesmente "sumir" porque o sistema caiu antes de publicar o evento no broker.

Neste artigo, quero mostrar como resolver esse tipo de problema implementando o Outbox Pattern e Domain Events usando um exemplo prático inspirado em um banco digital.

Problema

Imagine o fluxo de uma transferência entre contas:

O serviço registra a transação no banco de dados.
Em seguida, publica um evento no broker (RabbitMQ, Kafka, etc.)

Um fluxo simples de caminho feliz. Até o momento em que o servidor cai ou uma falha de rede acontece. A transação foi salva, mas o evento nunca chegou ao broker.
Resultado: inconsistência entre os sistemas.

Solução: Outbox Pattern

A ideia central do Outbox Pattern é armazenar os eventos junto com a transação do banco de dados, garantindo atomicidade.
Ou seja, ou tudo é persistido (entidade + evento), ou nada é.

Um processo em background lê periodicamente esses eventos na tabela OutboxMessages e os publica com segurança, marcando-os como processados.

Dessa forma, mesmo que o sistema caia, o evento continua guardado e será reenviado depois.

Cenário: Banco Digital

Nesta POC, o contexto é o de um banco digital com operações de transferência entre contas.

A estrutura da solução é a seguinte:

BancoDigital
├── Application
│   ├── Interfaces
│   └── UseCases
├── Domain
│   ├── Entidades
│   ├── Eventos
│   └── Abstracoes
├── Infrastructure
│   ├── DbContext (EF Core)
│   ├── Interceptors (Outbox)
│   ├── Outbox (OutboxDispatcher)
│   └── Serializers
└── BancoDigital.Api
    ├── DTOs
    └── Program.cs

> Aqui optei por adotar uma convenção de nomenclatura de abordagem mista inspirada nos princípios do Domain-Driven Design (DDD).
As camadas arquiteturais seguem a convenção tradicional em inglês (domain, application, infrastructure e interfaces) para manter compatibilidade com a literatura e frameworks amplamente utilizados.
Entretanto, todos os elementos do domínio (entidades, objetos de valor, serviços, eventos, casos de uso etc.) utilizam nomes em português, refletindo fielmente a linguagem ubíqua do negócio.

Entidades Principais

 public class Conta : ITemEventoDomain
 {
     private readonly List<EventoDomain> _eventosDomain = new();
     public IReadOnlyCollection<EventoDomain> EventosDomain => _eventosDomain.AsReadOnly();

     public Guid Id { get; private set; }
     public decimal Saldo { get; private set; }

     public Conta(Guid id, decimal saldoInicial = 0m)
     {
         Id = id;
         Saldo = saldoInicial;
     }

     public void Creditar(decimal valor)
     {
         if (valor <= 0) throw new ArgumentException("Valor deve ser positivo", nameof(valor));
         Saldo += valor;
     }

     public void Debitar(decimal valor)
     {
         if (valor <= 0) throw new ArgumentException("Valor deve ser positivo", nameof(valor));
         if (Saldo < valor) throw new InvalidOperationException("Saldo insuficiente");
         Saldo -= valor;
     }

     public void TransferirPara(Conta contaDestino, decimal valor)
     {
         Debitar(valor);
         contaDestino.Creditar(valor);

         _eventosDomain.Add(new TransferenciaRealizadaDomainEvent(
             ContaOrigemId: this.Id,
             ContaDestinoId: contaDestino.Id,
             Valor: valor
         ));
     }

     public void LimparEventosDomain() => _eventosDomain.Clear();
 }

A entidade de Conta dispara um EventoDomain automaticamente:

 public void TransferirPara(Conta contaDestino, decimal valor)
 {
     Debitar(valor);
     contaDestino.Creditar(valor);

     _eventosDomain.Add(new TransferenciaRealizadaDomainEvent(
         ContaOrigemId: this.Id,
         ContaDestinoId: contaDestino.Id,
         Valor: valor
     ));
 }

Tabela Outbox

Cada evento de domínio é serializado e armazenado em uma tabela auxiliar:

 public class OutboxMessage
 {
     public long Id { get; set; }
     public DateTime OccurredOnUtc { get; set; }
     public string Type { get; set; } = null!;
     public string Payload { get; set; } = null!;
     public DateTime? ProcessedOnUtc { get; set; }
     public string? Error { get; set; }
 }

Um interceptor do EF Core detecta os eventos e os grava nessa tabela dentro da mesma transação do banco.

public override async ValueTask<InterceptionResult<int>> SavingChangesAsync(
    DbContextEventData eventData,
    InterceptionResult<int> result,
    CancellationToken cancellationToken = default)
{
    var context = eventData.Context;
    if (context == null) return result;

    var aggregates = context.ChangeTracker
        .Entries()
        .Where(e => e.Entity is IHasDomainEvents hasEvents && hasEvents.DomainEvents.Any())
        .Select(e => (IHasDomainEvents)e.Entity)
        .ToList();

    if (!aggregates.Any()) return result;

    var outbox = context.Set<OutboxMessage>();

    foreach (var aggregate in aggregates)
    {
        foreach (var @event in aggregate.DomainEvents)
        {
            outbox.Add(new OutboxMessage
            {
                OccurredOnUtc = @event.OccurredOnUtc,
                Type = @event.GetType().AssemblyQualifiedName!,
                Payload = SystemTextJsonEventSerializer.Serialize(@event)
            });
            _logger.LogInformation("Outbox message {Type} stored ", @event.GetType().Name);
        }
        aggregate.ClearDomainEvents();
    }

    return result;
}

Processamento Assíncrono

O serviço OutboxDispatcher é executado em background. Ele busca eventos não processados e os "envia" para um broker:

 protected override async Task ExecuteAsync(CancellationToken stoppingToken)
 {
     while (!stoppingToken.IsCancellationRequested)
     {
         using var scope = _sp.CreateScope();
         var db = scope.ServiceProvider.GetRequiredService<BancoDigitalDbContext>();

         var pendentes = await db.OutboxMessages
             .Where(o => o.ProcessedOnUtc == null)
             .OrderBy(o => o.Id)
             .Take(50)
             .ToListAsync(stoppingToken);

         foreach (var msg in pendentes)
         {
             try
             {
                 var evt = SystemTextJsonEventSerializer.Deserialize(msg.Payload, msg.Type) as DomainEvent;
                 if (evt != null)
                 {                     
                     await SimulatedPublish(evt);  
                     msg.ProcessedOnUtc = DateTime.UtcNow;
                 }
             }
             catch (Exception ex)
             {
                 msg.Error = ex.Message;                 
             }
         }

         if (pendentes.Any())
         {
             await db.SaveChangesAsync(stoppingToken);
         }

         await Task.Delay(_pollInterval, stoppingToken);
     }
 }

Resultados

Com essa abordagem, a consistência é garantida:

O evento nunca se perde.
Falhas momentâneas no broker não impactam a transação.
O sistema continua eventual e previsivelmente consistente.

Exemplo de logs:

[INF] Outbox message TransferenciaRealizadaDomainEvent armazenada 
[INF] Evento TransferenciaRealizada publicado: d2ae0477-6d9b-44a2-bc10-849b6d11fef0 -> 8d425533-c790-4ec8-8bcb-79537dd318d1 : Valor 10

Próximos Passos

Integrar o Outbox com RabbitMQ ou Kafka.
Implementar retry policies com Polly.
Adicionar métricas e monitoramento da Outbox.

Referências

Artigo original: Reliable Messaging in .NET: Domain Events and the Outbox Pattern with EF Core Interceptors
Microsoft Docs – Interceptors in EF Core
Microsoft Docs – Worker services in .NET

Conclusão

O Outbox Pattern é um exemplo elegante de como simples decisões de arquitetura evitam grandes dores de cabeça em produção.

Em um sistema bancário, onde cada evento importa, ele se torna uma camada essencial de segurança transacional.

O código completo da POC está disponível no repositório:
https://github.com/josemarcosit/bancodigital-api

3 Tools for testing your kafka connection

José Marcos — Fri, 23 Oct 2020 18:59:25 +0000

Today, I needed to test whether my kafka broker was active. I used telnet for this, but I could also have used cUrl. These are 3 tools that you can use to test your kafka connection:

Tool 1 - telnet

Telnet is a tool that we use to make remote connections based on the telnet protocol.

The command is quite simple:

telnet [host/ip] [port]

Run the following command in your terminal:

telnet kafka-01 9092

Your terminal should look like this:

$ telnet kafka-01 9092
Trying 192.168.15.20...
Connected to kafka-01.
Escape character is '^]'.

Tool 2 - cUrl

cURL is a command-line tool that we use for transferring data from or to a server using various network protocols. I have been using this tool for testing connectivity from a pod running inside a Kubernetes cluster.

The commad syntax is:

curl [options...] url

--
$ curl -v telnet://kafka-01:9092
Trying 192.168.15.20:9092...
TCP_NODELAY set
Connected to kafka-01 (192.168.15.20) port 9092 (#0

Tool 3 - kafkacat

kafkacat is a powerful tool that you can use to produce, consume, list topics, and partitions. This tool is capable of creating or destroying your entire cluster. Be careful with this tool!

Run the following command in your terminal:

kafkacat -L -b kafka-01:9092

The arguments are -L for listing mode and -b for which Kafka broker to talk to.

Your terminal should look like this:

$ kafkacat -L -b kafka-01:9092
Metadata for all topics (from broker -1: kafka-01:9092/bootstrap):
1 brokers:
broker 0 at kafka-01:9092 (controller)
1 topics:
topic "topic-one" with 1 partition:

plus: You can also use these tools for testing your Azure Event Hubs connections.

Azure Event Hubs is a distributed stream processing platform and event ingestion service managed by Microsoft. You do not need to set up, configure, and manage your own Kafka clusters.

This is a terminal output for telnet:

$ telnet eventhub-01.servicebus.windows.net 9093
Trying [ip]...
Connected to [hostname].cloudapp.net.
Escape character is '^]'.

DEV Community: José Marcos