Kafka no Node.js: tópicos, partições e consumers

Kafka no Node.js permite publicar e consumir fluxos de eventos com retenção, particionamento e grupos de consumidores. Diferente de uma fila tradicional, eventos permanecem no log pelo período configurado e podem ser relidos por consumidores independentes.

Uma integração correta precisa escolher chaves de partição, controlar offsets, tratar rebalanceamento, duplicatas, backpressure e contratos. Kafka oferece alto throughput, mas não elimina as responsabilidades da aplicação.

Tópicos e partições

Um tópico é dividido em partições ordenadas. A ordem é garantida apenas dentro da partição. Eventos com a mesma chave devem usar a mesma estratégia de particionamento.

await producer.send({
  topic: 'orders.events',
  messages: [{
    key: orderId,
    value: JSON.stringify(event),
    headers: {
      eventType: 'order.created.v1',
      correlationId
    }
  }]
});

Usar orderId mantém ordem por pedido.

Producer

import { Kafka } from 'kafkajs';

const kafka = new Kafka({
  clientId: 'orders-api',
  brokers: process.env.KAFKA_BROKERS.split(','),
  ssl: true
});

const producer = kafka.producer({
  allowAutoTopicCreation: false
});

await producer.connect();

Desative criação automática em produção e gerencie tópicos como infraestrutura versionada.

Acknowledgements

A configuração de acknowledgements influencia durabilidade e latência. Para eventos críticos, espere confirmação adequada das réplicas conforme a política do cluster.

Consumer Groups

Consumidores com o mesmo groupId dividem partições. Grupos diferentes recebem o fluxo de forma independente.

const consumer = kafka.consumer({ groupId: 'billing-v1' });
await consumer.connect();
await consumer.subscribe({ topic: 'orders.events', fromBeginning: false });

await consumer.run({
  eachMessage: async ({ topic, partition, message }) => {
    const event = JSON.parse(message.value.toString());
    await processar(event);
  }
});

Offsets

O offset indica a posição consumida. Confirmar cedo pode perder processamento; confirmar tarde pode repetir mensagens após falha. Prefira efeitos idempotentes.

Processamento em lote

eachBatch oferece controle de offsets, heartbeat e backpressure para workloads maiores.

await consumer.run({
  eachBatchAutoResolve: false,
  eachBatch: async ({ batch, resolveOffset, heartbeat, isRunning }) => {
    for (const message of batch.messages) {
      if (!isRunning()) break;
      await processar(JSON.parse(message.value.toString()));
      resolveOffset(message.offset);
      await heartbeat();
    }
  }
});

Rebalanceamento

Quando consumidores entram ou saem, partições são redistribuídas. Processamento lento sem heartbeat pode causar rebalanceamentos repetidos. Ajuste timeouts e não bloqueie a thread com CPU intensa.

Idempotência do consumidor

Kafka pode entregar novamente eventos após falhas. Registre o ID do evento junto com o efeito local.

await db.transaction(async trx => {
  const novo = await inbox.registrar(event.id, trx);
  if (!novo) return;
  await saldo.aplicar(event, trx);
});

Partições e escala

O número de consumidores ativos de um grupo não ultrapassa o número de partições. Partições demais aumentam overhead; poucas limitam paralelismo.

Hot partitions

Uma chave muito concentrada cria uma partição sobrecarregada. Analise distribuição de chaves e considere granularidade alternativa sem quebrar a ordem necessária.

Retenção e replay

Kafka retém eventos por tempo ou tamanho. Um novo grupo pode ler histórico e criar uma projeção. Replays devem ser controlados para não repetir efeitos externos como e-mails.

Compaction

Tópicos compactados mantêm o valor mais recente por chave, além das regras de retenção. São úteis para representar estado, mas exigem chave estável e tratamento de tombstones.

Schema e compatibilidade

Use schemas versionados e regras de compatibilidade. Avro, Protobuf e JSON Schema são opções comuns. Produtores não devem quebrar consumidores existentes.

Dead Letter Topic

Eventos inválidos ou com falha permanente podem ir para um tópico de erro. Inclua evento original, erro classificado, tentativas e posição.

Retries

Retry dentro da partição pode bloquear eventos posteriores. Alternativas incluem tópicos de retry com atraso, processamento paralelo controlado ou pausa da partição.

Outbox e Kafka

Para publicar depois de uma transação de banco, use Outbox Pattern no Node.js. Isso evita perder eventos entre commit e envio.

Segurança

Configure TLS, SASL quando aplicável, ACL por tópico e credenciais por aplicação. Não exponha brokers diretamente à internet.

Observabilidade

Monitore consumer lag, throughput, erros, rebalanceamentos, tamanho dos lotes, tempo de processamento, retries e partições sem líder.

Graceful shutdown

Pare consumo, aguarde processamento atual, desconecte consumer e producer. Em ambientes orquestrados, alinhe o período de terminação com o tempo máximo de uma mensagem.

Testes

• chave e partição corretas;
• mensagem duplicada;
• evento inválido;
• rebalanceamento;
• retry e tópico de erro;
• replay;
• shutdown;
• compatibilidade de schema.

Erros comuns

• esperar ordem global;
• sem chave de partição;
• consumer não idempotente;
• processamento bloqueando heartbeat;
• auto-commit incompatível com o efeito;
• tópico sem contrato;
• replay acionando efeitos externos;
• não monitorar lag.

Conclusão

Kafka no Node.js é adequado para logs de eventos, integração entre serviços e projeções reprocessáveis. A confiabilidade depende de particionamento, offsets, idempotência e operação do cluster.

Combine Kafka com contratos versionados, Outbox e métricas de lag. Leia Event-Driven Architecture no Node.js.

Consulte a documentação oficial do Apache Kafka e a documentação do KafkaJS.