O problema das mensagens duplicadas

Objetivos

• Entender por que duplicidade ocorre em sistemas at-least-once
• Reproduzir redelivery e observar efeitos colaterais no negócio
• Definir onde aplicar idempotência no stack de 5 microsserviços

Pré-requisitos

• Docker e Docker Compose instalados.
• Kafka e Redis já funcionando com docker compose up -d.
• Fluxo order.created -> payment.approved -> notification.sent operacional.

Conceito

Em arquitetura orientada a eventos, o broker pode reenviar uma mensagem quando o consumer falha antes de confirmar o offset. Isso e esperado em at-least-once.

Sem idempotencia, o mesmo evento pode aprovar pagamento duas vezes, enviar notificacao duplicada ou inflar metricas de analytics.

Estrutura de arquivos

• services/payment-service/internal/consumers/order_created_consumer.go
• services/notification-service/app/consumers/payment_approved_consumer.rb
• services/analytics-service/src/consumers/notificationSentConsumer.ts
• docs/architecture/idempotencia.md

Passo a passo com codigo

1. Adicionar eventId no payload de teste para rastrear duplicidade:

{
  "eventId": "evt-ord-9001",
  "eventType": "order.created",
  "occurredAt": "2026-07-03T18:00:00Z",
  "data": {
    "orderId": "ord-9001",
    "customerId": "cus-101",
    "amount": 199.90
  }
}

2. Publicar duas vezes o mesmo evento no topico order.created:

kcat -b localhost:9092 -t order.created -P <<'EOF'
{"eventId":"evt-ord-9001","eventType":"order.created","data":{"orderId":"ord-9001","amount":199.90}}
{"eventId":"evt-ord-9001","eventType":"order.created","data":{"orderId":"ord-9001","amount":199.90}}
EOF

3. Instrumentar log no Payment Service para evidenciar repeticao:

logger.Infow("received order.created",
  "event_id", event.EventID,
  "order_id", event.Data.OrderID,
)

4. Registrar impacto de negocio antes da deduplicacao:

• duas tentativas de cobranca para orderId=ord-9001;
• duas mensagens payment.approved publicadas;
• analytics contabilizando o dobro.

Como testar

1. Suba o ambiente: docker compose up -d.
2. Publique o mesmo evento duas vezes (com mesmo eventId).
3. Rode docker compose logs payment-service.
4. Confirme que o consumidor processou em duplicidade (ainda sem protecao).
5. Documente os efeitos para comparar com a proxima aula.

Dicas

• Trate duplicidade como requisito funcional, nao como edge case.
• Sempre transporte eventId e occurredAt.
• Log estruturado com event_id acelera troubleshooting.
• Comece por fluxos financeiros e de notificacao.

Erros comuns

• Assumir que Kafka nunca fara redelivery.
• Confiar so em offset commit para evitar duplicata.
• Ignorar consumers secundarios (analytics e notification).
• Deixar o eventId opcional no contrato.

Resumo

A duplicidade faz parte de sistemas at-least-once. Antes de corrigir, voce precisa reproduzir, medir impacto e mapear pontos criticos onde idempotencia e obrigatoria.