Transactional Outbox

Problema

Um serviço precisa gravar uma mudança de negócio e avisar outros serviços. Se a gravação e a publicação são operações separadas, qualquer falha no meio deixa um dos lados sem o outro.

No pedido, isso aparece de dois jeitos. O commit pode acontecer e o evento se perder. Ou o broker pode aceitar OrderCreated e a transação local falhar, deixando um evento sem o pedido. Uma nova tentativa do POST ainda pode criar um segundo pedido.

Antes e depois

Sem Outbox, gravar o pedido e publicar são operações separadas. No fluxo normal o commit vem primeiro. A falha do Kafka deixa o pedido sem evento. A outra ordem publica primeiro: se a transação falha depois, o evento fica sem o pedido.

Com Outbox, o serviço grava o pedido e a mensagem na mesma transação local. A API responde em seguida. Um worker publica as mensagens pendentes e marca o que já foi enviado.

Prós e contras

Quando usar

Use o padrão quando perder o evento causa divergência de negócio e a publicação precisa ocorrer depois de um commit local bem-sucedido.

Exemplo em .NET

Os dois registros usam o mesmo contexto e a mesma transação do banco. O dispatcher abaixo é intencionalmente incompleto: falta a reserva atômica, o limite de tentativas e o tratamento da falha entre o ack e a atualização da Outbox.

// Fragmento ilustrativo. Orders e OutboxMessages usam o mesmo DbContext
// e a mesma transação do banco. Isto não é uma transação distribuída.

await using var transaction =
    await dbContext.Database.BeginTransactionAsync(cancellationToken);

var order = Order.Create(request.CustomerId);

dbContext.Orders.Add(order);
dbContext.OutboxMessages.Add(
    OutboxMessage.Create(
        eventType: "OrderCreated",
        payload: JsonSerializer.Serialize(new OrderCreated(order.Id))));

await dbContext.SaveChangesAsync(cancellationToken);
await transaction.CommitAsync(cancellationToken);

// Dispatcher simplificado de propósito.
// Esta versão não reserva a mensagem com atualização condicional,
// não limita tentativas e não trata a falha entre o ack do broker
// e a atualização da Outbox.

var pending = await dbContext.OutboxMessages
    .Where(message => message.Status == OutboxStatus.Pending)
    .OrderBy(message => message.OccurredAt)
    .Take(20)
    .ToListAsync(cancellationToken);

foreach (var message in pending)
{
    await producer.ProduceAsync(
        topic: "orders",
        key: message.Id.ToString(),
        payload: message.Payload,
        cancellationToken);

    message.MarkProcessed();
}

await dbContext.SaveChangesAsync(cancellationToken);

O que o Outbox não garante

• Não garante, sozinho, entrega exatamente uma vez.
• Uma mensagem pode ser publicada mais de uma vez se o processo falhar depois do ack e antes de atualizar a Outbox.
• Consumidores idempotentes reduzem o efeito dessa repetição. Idempotência não é opcional neste desenho.
• O dispatcher precisa reservar mensagens, limitar tentativas e separar o que é falha transitória do que está permanentemente inválido.
• A confirmação do broker e a atualização da Outbox não formam uma transação atômica.
• Polling e CDC transportam a mesma tabela por caminhos diferentes. O cenário mostra polling.
• O limite de três tentativas e os nomes das tabelas são escolhas didáticas.