Boas Práticas

Modelagem de Eventos

1. Eventos no passado: PedidoCriado, não CriarPedido. Eventos descrevem o que aconteceu.
2. Schema explícito: use Avro, Protobuf ou JSON Schema. Nunca confie só no JSON livre.
3. Versionamento: adicione campo schema_version. Evolução é inevitável.
4. Eventos pequenos e focados: 1 evento = 1 fato. Não junte coisas só pra "economizar".
5. Inclua metadados: event_id, event_type, occurred_at, correlation_id, producer_name.

Topics

1. Naming convention clara: <dominio>.<entidade>.<evento>, ex: vendas.pedido.criado.
2. Não compartilhe topics entre domínios não relacionados.
3. Particione com cuidado: difícil aumentar depois (quebra ordem). Comece com pelo menos 6 partições para topics importantes.
4. Configure retenção: retention.ms define quanto tempo o Kafka guarda. Padrão é 7 dias. Avalie.

Producer

1. acks=all em produção. Sempre.
2. Habilite idempotência (enable.idempotence=true em libs que suportam).
3. Defina key: para eventos de uma mesma entidade.
4. Trate erros de publicação explicitamente — não esconda exceptions.
5. Use compressão: snappy ou lz4. Reduz banda e custo.

Consumer

1. Comite offset depois de processar, nunca antes.
2. Idempotência sempre.
3. Não bloqueie indefinidamente: timeouts em chamadas externas são obrigatórios.
4. Monitore o lag: diferença entre último offset publicado e último consumido. Lag crescente = problema.
5. Trate envenenamento: mensagem que sempre falha não pode bloquear a fila eternamente. Use DLQ.

Observabilidade

• Métricas obrigatórias: lag por partição, mensagens/segundo, erros por consumer, tamanho da DLQ.
• Tracing distribuído: propague traceId nos headers da mensagem.
• Logs estruturados: sempre incluam event_id, partition, offset.
• Alertas: lag alto, DLQ crescendo, consumer fora do ar.

Anti-Patterns (não faça)

• Usar Kafka como banco de dados primário (não é).
• Mensagens gigantes (>1MB). Coloque o payload em S3 e mande só a referência.
• Ignorar a DLQ. DLQ sem alerta é cemitério maldito.
• Eventos com lógica de comando ("ExecutarCobranca"). Eventos descrevem fatos, comandos pedem ações — são coisas diferentes.
• Consumer que processa rápido demais sem idempotência. Vai duplicar e ninguém vai entender por quê.
• Mudar schema sem versionar. Vai quebrar todos os consumers de uma vez.