Kafka: topics, partitions, offsets e groups

Objetivos

• Criar e inspecionar tópicos Kafka no ambiente local
• Entender efeito de partições na ordem e paralelismo
• Configurar consumer group para o order-service

Pré-requisitos

• Kafka disponível no Docker Compose
• Conceitos da aula REST vs eventos
• Serviços customer e order prontos

Conceito

Tópico é o canal lógico de mensagens. Partição é a unidade física de ordenação e paralelismo. Offset é a posição da mensagem dentro de cada partição. Esses três conceitos explicam quase todo comportamento do Kafka em produção.

Quando você escolhe mal partições ou chave da mensagem, o sistema perde ordenação onde deveria manter e engasga onde poderia escalar. Por isso, configurar tópico não é detalhe de infra: é decisão de arquitetura de dados.

Nesta aula, você cria o tópico customer.created.v1, publica eventos de teste e observa como o order-service consome com group.id próprio.

Estrutura de arquivos

infra/docker-compose.yml
services/order-service/app/consumers/customer_created_consumer.py
services/order-service/app/config.py
contracts/events/customer-created.v1.json

Passo a passo

1. Garantir Kafka no infra/docker-compose.yml

kafka:
  image: bitnami/kafka:3.7
  ports:
    - "9092:9092"
  environment:
    - KAFKA_CFG_NODE_ID=1
    - KAFKA_CFG_PROCESS_ROLES=broker,controller
    - KAFKA_CFG_CONTROLLER_QUORUM_VOTERS=1@kafka:9093
    - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092,CONTROLLER://:9093
    - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://kafka:9092
    - KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP=PLAINTEXT:PLAINTEXT,CONTROLLER:PLAINTEXT
    - KAFKA_CFG_CONTROLLER_LISTENER_NAMES=CONTROLLER

2. Configurar consumidor Python com group id

# services/order-service/app/config.py
KAFKA_BROKERS = "kafka:9092"
CUSTOMER_TOPIC = "customer.created.v1"
CONSUMER_GROUP = "order-service-customer-group"

3. Implementar loop de consumo (customer_created_consumer.py)

import json
from kafka import KafkaConsumer
from app.config import KAFKA_BROKERS, CUSTOMER_TOPIC, CONSUMER_GROUP

consumer = KafkaConsumer(
    CUSTOMER_TOPIC,
    bootstrap_servers=KAFKA_BROKERS,
    group_id=CONSUMER_GROUP,
    auto_offset_reset="earliest",
    enable_auto_commit=True,
)

for msg in consumer:
    event = json.loads(msg.value.decode("utf-8"))
    print(f"[order-service] topic={msg.topic} partition={msg.partition} offset={msg.offset} event={event}")

4. Criar tópico e publicar eventos de teste via CLI Kafka

docker compose -f infra/docker-compose.yml exec kafka \
  kafka-topics.sh --create --topic customer.created.v1 --partitions 3 --replication-factor 1 --bootstrap-server kafka:9092

docker compose -f infra/docker-compose.yml exec kafka \
  kafka-console-producer.sh --bootstrap-server kafka:9092 --topic customer.created.v1

Como testar

1. Subir ambiente:

docker compose -f infra/docker-compose.yml up -d kafka order-service

2. Listar tópico e detalhes:

docker compose -f infra/docker-compose.yml exec kafka \
  kafka-topics.sh --describe --topic customer.created.v1 --bootstrap-server kafka:9092

Saída esperada: tópico com PartitionCount:3.

3. Produzir uma mensagem de teste:

{"eventId":"evt-1","customerId":"c-100","email":"c100@aprendi.dev","occurredAt":"2026-07-03T18:00:00Z"}

4. Ver consumo nos logs:

docker compose -f infra/docker-compose.yml logs -f order-service

Saída esperada inclui partition= e offset=.

Dicas de projeto

• Partições devem refletir expectativa real de throughput.
• Use chave de negócio para preservar ordem por entidade.
• Nomeie tópico com semântica e versão (domain.event.v1).
• Monitore lag do consumer group desde cedo.

Erros comuns

• Criar tópico com 1 partição e depois sofrer para escalar.
• Consumidor sem group.id, perdendo coordenação.
• Ignorar auto_offset_reset e perder eventos no bootstrap.
• Não registrar partition/offset nos logs.

Resumo

Você configurou o tópico, consumer group e observou offsets na prática. Agora o projeto tem infraestrutura Kafka compreendida e pronta para discutir garantias de entrega.