Particionamento e ordem das mensagens

Objetivos

• Preservar ordem por chave de negócio relevante
• Definir estratégia de partição para eventos de pagamento
• Equilibrar paralelismo com consistência de sequência

Pré-requisitos

• Aula consumer-groups-por-dentro concluida.
• Topico order.created com multiplas particoes.
• Conhecimento basico de chave de particao no Kafka.

Conceito

A ordem no Kafka e garantida apenas dentro da mesma particao. Para manter sequencia de eventos do mesmo pedido, todos eles devem cair na mesma particao.

Por isso, escolha da key (orderId, por exemplo) e decisao de negocio: ela define consistencia e distribuicao de carga.

Estrutura de arquivos

• services/order-service/app/events/publish_order_created.py
• services/payment-service/internal/consumers/order_created_consumer.go
• contracts/events/order.created.schema.json
• docs/architecture/event-partitioning.md

Passo a passo com codigo

1. Publique eventos usando orderId como chave:

producer.produce(
    topic="order.created",
    key=order_id.encode(),
    value=json.dumps(payload).encode(),
)

2. Logue chave e particao no producer:

logger.info("published order.created", extra={
    "order_id": order_id,
    "event_id": event_id
})

3. No consumer, exiba particao e offset:

logger.Infow("event consumed",
  "order_id", event.Data.OrderID,
  "partition", msg.Partition,
  "offset", msg.Offset,
)

4. Gere eventos alternando pedidos:

python scripts/publish_orders.py --orders ord-1,ord-1,ord-2,ord-1,ord-2

Como testar

1. Execute o script de publicacao com pedidos repetidos.
2. Valide nos logs que eventos de ord-1 preservam ordem.
3. Confirme que ord-1 e ord-2 podem ir para particoes diferentes.
4. Verifique inexistencia de reorder dentro da mesma chave.

Dicas

• Use chave deterministica e imutavel.
• Formalize no contrato qual campo e usado para particionar.
• Observe skew de chave em producao.
• Evite particao unica para todo o sistema.

Erros comuns

• Particionar por campo volátil
• Assumir ordem entre partições diferentes
• Trocar chave sem plano de migração
• Ignorar skew de distribuição por chave

Resumo

Particionamento por chave de negocio garante ordem onde importa e libera paralelismo entre entidades diferentes, mantendo consistencia sem perder throughput.