Design de Payloads em Arquitetura Orientada a Eventos: Dados vs. Chave-Valor

Você já publicou uma mensagem em um broker de eventos e se perguntou se deveria colocar todos os dados dentro dela ou apenas um identificador? Essa decisão, que parece simples à primeira vista, é uma das mais críticas no design de sistemas distribuídos e pode determinar se sua arquitetura vai escalar com elegância ou virar um pesadelo de acoplamento e latência.

Quando um serviço publica uma mensagem em um broker como Kafka, RabbitMQ ou Redis, a estrutura dessa mensagem dita não apenas como o consumidor vai processá-la, mas também o nível de acoplamento, a performance e a resiliência de toda a plataforma. Escolher mal pode significar desde uma sobrecarga silenciosa na sua API de leitura até violações de privacidade de dados.

Neste artigo, vamos explorar as duas das principais estratégias de modelagem de eventos, uma terceira abordagem que combina o melhor dos dois mundos, e um guia prático para tomar a decisão certa no seu projeto.

1. Payloads Baseados em Dados

A abordagem baseada em dados, ocorre quando o evento publicado carrega consigo todo as informações ou um subconjunto rico o suficiente.

Em vez de apenas avisar que "algo aconteceu", o produtor do evento envia o "filme completo". Se um pedido de e-commerce é criado, o evento conterá os dados do cliente, os itens comprados, os valores, os endereços e os status de pagamento.

Exemplo Prático

Imagine um sistema de e-commerce onde o serviço de pedidos publica um evento para notificar os demais serviços (pagamento, estoque, notificação, analytics) sobre uma nova compra:

{
  "event_id": "evt_987654321",
  "event_type": "order.created",
  "timestamp": "2026-07-19T10:30:00Z",
  "data": {
    "order_id": "ord_123",
    "customer": {
      "id": "cust_456",
      "name": "Maria Silva",
      "email": "maria@example.com"
    },
    "items": [
      { "sku": "ABC-123", "quantity": 2, "price": 49.90 },
      { "sku": "XYZ-987", "quantity": 1, "price": 120.00 }
    ],
    "total_amount": 219.80,
    "shipping_address": {
      "city": "Juazeiro do Norte",
      "state": "CE",
      "zip_code": "63000-000"
    },
    "payment_method": "credit_card"
  }
}

Por que isso importa?

Quando o consumidor recebe essa mensagem, ele tem tudo o que precisa para processar o evento sem fazer nenhuma chamada de volta ao produtor. O serviço de pagamento já sabe o valor, o serviço de estoque já sabe os SKUs e quantidades, e o serviço de notificação já tem o e-mail do cliente.

Vantagens

• Desacoplamento Absoluto: O consumidor tem tudo que precisa na mensagem. Não há necessidade de requisições HTTP síncronas de volta ao produtor para buscar detalhes. Isso é especialmente valioso quando o produtor pode estar temporariamente indisponível.

• Alta Disponibilidade e Resiliência: Se o serviço produtor cair logo após publicar a mensagem, os consumidores continuam processando normalmente. O sistema tolera falhas parciais de forma elegante, um princípio fundamental da Arquitetura Orientada a Eventos.

• Menor Carga no Banco de Dados (Leitura): O banco do produtor é poupado. Se cinco microsserviços diferentes estão interessados no evento order.created, enviar os dados no payload evita que sua API sofra requisições de leitura quase simultâneas.

Desvantagens

• Tamanho do Payload: Mensagens grandes consomem mais banda de rede e mais espaço de armazenamento no broker. No Kafka, por exemplo, payloads muito grandes podem impactar o desempenho de compactação e replicação.

• Risco de Dados Desatualizados (Staleness): Se o consumidor demorar a processar a mensagem, os dados podem ter sido alterados na origem. Imagine que o preço de um produto mudou entre a publicação e o processamento, o consumidor terá dados desatualizados.

• Complexidade de Contrato (Schema Evolution): O produtor expõe sua estrutura interna. Qualquer mudança exige cuidado extremo com compatibilidade reversa. Esse tipo de complexidade de contrato é um sinal clássico de quando a modularização de código precisa ser repensada — nem toda mudança de schema justifica uma nova camada de abstração.

• Segurança e Privacidade (LGPD/GDPR): Informações sensíveis (e-mails, CPFs, endereços) ficam armazenadas nos logs do broker, exigindo controles rígidos de criptografia e retenção. Isso pode ser um problema sério em ambientes regulamentados.

Quando Usar

• Sistemas que precisam de máxima resiliência e tolerância a falhas
• Cenários onde a latência de processamento é crítica
• Ambientes com múltiplos consumidores que precisam dos mesmos dados

2. Payloads Baseados em Chave-Valor

A abordagem de chave-valor (ou notificação de evento) é minimalista. O payload atua apenas como um "sinalizador". Ele informa que um evento ocorreu e fornece um identificador (a chave) para que o consumidor, se estiver interessado, busque os detalhes completos via API.

Exemplo Prático

No mesmo cenário de e-commerce, a notificação ficaria assim:

{
  "event_id": "evt_987654322",
  "event_type": "order.created",
  "timestamp": "2026-07-19T10:30:05Z",
  "data": {
    "order_id": "ord_123",
    "status": "created"
  },
  "metadata": {
    "correlation_id": "corr_789",
    "source": "order-service"
  }
}

O consumidor recebe a notificação e, se precisa dos dados completos, faz uma chamada HTTP para a API do produtor ou consulta em banco de dados:

GET https://api.empresa.com/v1/orders/ord_123
Authorization: Bearer <token>

Por que isso importa?

Essa abordagem é a base de muitos sistemas de webhooks que usamos no dia a dia. Quando notifica sua aplicação sobre um pagamento, ele envia um payload mínimo e sua aplicação busca os detalhes na API. O mesmo vale para webhooks do GitHub, Slack e muitos outros serviços.

Vantagens

• Payloads Leves e Rápidos: O tamanho da mensagem é mínimo, permitindo altíssimo throughput. Isso é crucial em brokers como o Kafka, onde a performance de escrita é diretamente impactada pelo tamanho das mensagens.

• Dados Sempre Atualizados (Consistency): O consumidor sempre faz o fetch do estado atualizado. Não existe o problema de "staleness" se o preço mudou, ele vai ver o preço novo.

• Segurança Reforçada: O broker não armazena dados sensíveis. O acesso real é restrito às camadas de autenticação da API do produtor, seguindo o princípio de menor privilégio.

• Flexibilidade de Contrato: A evolução dos dados acontece apenas na API do produtor. O contrato do evento (a notificação) permanece estável, facilitando a manutenção.

Desvantagens

• Acoplamento Temporal: A API do produtor precisa estar no ar no momento exato em que o consumidor faz o callback. Se a API cair, o consumidor não consegue processar o evento criando um ponto único de falha.

• Sobrecarga de API: Cada evento gera uma requisição de volta. Se um evento de alta frequência como user.clicked_button gerar milhares de chamadas por minuto, sua API pode colapsar.

• Maior Latência de Processamento End-to-End: A buscar pelos dados adiciona latência. Em sistemas que precisam de processamento em tempo real, isso pode ser inaceitável.

• Complexidade de Rastreamento: Depurar exige correlacionar logs de mensageria e de API. Quando algo dá errado, você precisa rastrear a mensagem no broker, a chamada HTTP e o processamento no consumidor, três pontos de observabilidade.

Quando Usar

• Webhooks e integrações externas (Stripe, GitHub, Slack)
• Cenários onde a segurança é prioridade e dados sensíveis não podem ficar no broker
• Quando a precisão do estado em tempo real é inegociável
• Sistemas com baixa frequência de eventos

3. Abordagem Híbrida: O Melhor dos Dois Mundos

Na prática, muitas equipes não escolhem apenas uma das duas abordagens, elas combinam as duas conforme a necessidade de cada evento. Essa é a abordagem híbrida, e é provavelmente a mais utilizada em sistemas de produção maduros.

Como Funciona?

A ideia é simples: para cada tipo de evento, avaliar qual abordagem se encaixa melhor. Em um mesmo sistema, você pode ter:

• Eventos críticos de alta frequência (ex: order.created, payment.processed) usando payloads completos com dados, para garantir resiliência e baixa latência.
• Eventos de baixa frequência ou de integração externa (ex: report.generated, export.completed) usando notificações com chave, já que o consumidor pode buscar os detalhes via API sem problema.
• Eventos híbridos que enviam um payload parcial, apenas os dados mais importantes e deixam o restante para busca via API.

Exemplo de Evento Híbrido

{
  "event_id": "evt_987654323",
  "event_type": "order.created",
  "timestamp": "2026-07-19T10:30:10Z",
  "data": {
    "order_id": "ord_123",
    "customer_email": "maria@example.com",
    "total_amount": 219.80,
    "items_count": 3
  },
  "resource_url": "https://api.empresa.com/v1/orders/ord_123"
}

Nesse caso, o consumidor já tem o e-mail (para notificações imediatas), o valor total (para analytics) e a quantidade de itens (para validações rápidas). Se precisar dos itens detalhados ou do endereço de entrega, faz a chamada para o resource_url.

Vantagens da Abordagem Híbrida

• Flexibilidade Máxima: Cada evento é modelado de acordo com as necessidades reais do consumidor.
• Balanceamento de Trade-offs: Você mitiga os pontos fracos de cada abordagem isoladamente.
• Evolução Gradual: Pode começar com uma abordagem e migrar para a outra conforme o sistema amadurece.

Desafios

• Governança de Contratos: Com múltiplos padrões de payload, a documentação e o versionamento ficam mais complexos.
• Consistência de Padrão: Equipes diferentes podem escolher abordagens diferentes para o mesmo tipo de evento, gerando confusão.
• Necessidade de Diretrizes Claras: É fundamental ter um guia interno de quando usar cada abordagem.

4. Guia de Decisão: Como Escolher?

A escolha ideal vai depender dos requisitos do seu projeto. Aqui está um guia prático para te ajudar a decidir:

Escolha Payloads Baseados em Dados quando:

• Sua aplicação precisa de máxima resiliência e tolerância a falhas do produtor
• A latência de processamento é um requisito crítico
• Você tem múltiplos consumidores independentes que precisam dos mesmos dados
• Está implementando CQRS com projeções materializadas
• O custo de chamadas de API de retorno é proibitivo (escala alta)

Escolha Payloads Baseados em Chave-Valor quando:

• Você está integrando com sistemas externos (webhooks do Stripe, GitHub, etc.)
• A segurança é prioridade e dados sensíveis não podem ficar no broker
• A precisão do estado em tempo real é inegociável
• A frequência de eventos é baixa e o round-trip HTTP não é problema
• O contrato do evento precisa ser extremamente estável

Escolha a Abordagem Híbrida quando:

• Seu sistema tem diferentes tipos de eventos com necessidades distintas
• Você quer flexibilidade para evoluir a arquitetura gradualmente
• Está em uma fase de migração de uma abordagem para a outra
• Diferentes equipes mantêm diferentes serviços e precisam de autonomia

Perguntas-Chave para a Decisão

Antes de escolher, faça estas perguntas ao seu time:

1. O produtor vai estar sempre disponível? Se não, use dados no payload.
2. Os consumidores precisam dos dados completos ou apenas de uma notificação? Se completos, use dados. Se notificação, use chave.
3. Existem requisitos de segurança (LGPD/GDPR)? Se sim, prefira chave-valor ou híbrido com payloads sanitizados.
4. Qual a frequência dos eventos? Alta frequência favorece dados no payload (evita thundering herd na API).
5. Quantos consumidores existem por evento? Múltiplos consumidores favorecem dados no payload.

5. Considerações Finais

Não existe resposta universal para o design de payloads em EDA. A escolha entre dados, chave-valor ou híbrido depende do contexto do seu sistema, dos requisitos de performance, segurança e disponibilidade.

O mais importante é entender os trade-offs de cada abordagem e tomar uma decisão consciente — documentada e compartilhada com o time. Evite cair no extremismo de usar apenas uma abordagem para tudo; na prática, os sistemas maduros quase sempre adotam uma mistura das duas.

Lembre-se: o objetivo final de uma arquitetura orientada a eventos é criar sistemas desacoplados, resilientes e evolutivos. O design do seu payload é a pedra angular para alcançar esse objetivo. Esses mesmos princípios se aplicam quando estamos construindo agentes de IA com frameworks como Pydantic AI e LangChain, que precisam interagir com eventos de forma eficiente.

Leituras Recomendadas

Para se aprofundar no assunto, recomendo fortemente a leitura destas obras fundamentais:

• Fundamentos da Arquitetura de Software (2ª Edição) — Mark Richards e Neal Ford
• Designing Event-Driven Systems — Ben Stopford (Confluent)
• Enterprise Integration Patterns — Gregor Hohpe e Bobby Woolf

No seu cenário atual, qual abordagem faz mais sentido para o seu projeto? Já passou pelo dilema de escolher entre payloads completos e notificações mínimas? Compartilhe sua experiência nos comentários!