Plataformas, Microsserviços, DevOps e APIs · Hands-on 10

Hands-on 10 — Mensageria com Kafka

Um produtor acrescenta a um log e responde; um consumidor o lê no seu próprio tempo — primeiro o par de referência, depois a loja

O e-mail deve bloquear o cliente?

Toda chamada do order-service acontece antes de ele responder. Agora ele precisa enviar um e-mail de confirmação. Mais uma chamada REST?

REST
POST /orders
→
account, product
→
serviço de e-maillento ou fora do ar: o pedido espera ou falha
→
201
Kafka
POST /orders
→
account, product
→
acrescenta a um tópicoum log durável
→
201 na hora
depois, no tempo dele: o notification-service lê o tópico e envia o e-mail

Dois passos: a referência, depois a loja

Referência
GET /producer/{msg}
→
producer-service
send →
store-producer-examplesem chave
→
consumer-servicegrupo store
Loja
POST /orders
→
order-servicedepois de salvar
send →
order-eventschave = id do pedido
→
notification-servicegrupo notification-group
  • O mesmo padrão duas vezes: dois serviços Spring Boot que nunca chamam um ao outro.
  • O produtor não sabe quem lê; um novo leitor (analytics) é um novo grupo, não uma mudança de código.

Um tópico é um log

partição 0
0hello
1world
2a
3b
4c
5próxima escrita
lidos e confirmados pelo grupo store
esperando: atraso = 5 − 2 = 3
offset final 5
  • O produtor acrescenta; um registro ganha o próximo offset e fica — ler não o apaga.
  • O Kafka guarda, por grupo e partição, o offset confirmado: o próximo registro que esse grupo vai ler.
  • Atraso (lag) = offset final do log − offset confirmado. Outro grupo lê o mesmo log a partir do seu próprio offset.

2 · Kafka no Docker Compose

rede do Docker
producer · consumerbootstrap-servers: kafka:9092
PLAINTEXT →
kafka · um nó, KRaftbroker + controlador · :9092 clientes · :9093 quórum de controladores
sem portas →
sua máquinaas ferramentas rodam dentro do container
  • KRaft: o Kafka guarda os metadados no seu próprio quórum Raft; o Kafka 4.0 removeu o ZooKeeper.
  • ADVERTISED_LISTENERS: kafka:9092 — o nome do serviço; num container, localhost é o próprio container.
  • Um tópico é criado no primeiro uso com KAFKA_NUM_PARTITIONS: 1; um broker → fator de replicação 1.

A referência usa apache/kafka:latest (4.3.1 quando escrito); fixe a versão para builds reprodutíveis.

3 · O producer-service

GET /producer/hello
→
ProducerResource
→
ProducerServiceMap → JSON (ObjectMapper)
→
kafkaTemplate.send(topic, json) · sem chave
→
200entregue ao buffer do cliente
Map<String, String> map = Map.of("id", id, "message", msg);
kafkaTemplate.send("store-producer-example", objectMapper.writeValueAsString(map));
  • KafkaProducerConfig: o endereço do broker + StringSerializer para chave e valor — nada mais.
  • send é assíncrono: 200 = "entregue ao cliente do Kafka", não "gravado".
  • Desde o Kafka 3.0 os padrões são seguros: acks=all e idempotência ligada.

3.1 · Pelo gateway

curl
→
lb :8080
→
gatewayrota Path=/producer/**
→
RouterValidator"GET /producer/**" está aberta: sem cookie
→
producer:8080
  • Sem a rota: 404. Sem a entrada aberta: 401 (a rota exige login).

Um GET aberto que publica é só uma demonstração: qualquer um escreve no tópico e um crawler ou um prefetch publicariam também. Na loja, o evento sai de POST /orders, uma rota protegida.

4 · O consumer-service

listener containerfaz poll em store-producer-example
→
@KafkaListenerchamado uma vez por registro
→
todos os registros do poll prontos
→
confirma os offsetsAckMode.BATCH
↺
@KafkaListener(topics = "store-producer-example", groupId = "store")
public void consumerMsg(String message) { … logger.debug("enqueue {}", map); }
  • O método nunca chama poll() nem commit(): o container chama, com enable.auto.commit=false.
  • Uma queda antes do commit → esses registros voltam: at-least-once (seção 8).

O pom.xml é o do produtor com artifactId consumer-service — mantenha o antigo e o jar ganha o nome do produtor.

5 · Rode a referência

cd api/producer-service && mvn clean package -DskipTests && cd ../..
cd api/consumer-service && mvn clean package -DskipTests && cd ../..
cd api && docker compose up -d --build
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/producer/hello     # 200
producer-1queue {id=e295…, message=hello}
→
store-producer-examplepartição 0 · offset 0
→
consumer-1enqueue {id=e295…, message=hello}
Ferramenta (dentro do container kafka) Mostra
kafka-topics.sh --describe --topic … partições, líder, réplicas
kafka-console-consumer.sh --from-beginning os registros, ainda lá depois de lidos
kafka-consumer-groups.sh --describe --group store offset confirmado, offset final, atraso

5.2 · O consumidor estava fora do ar

docker compose stop consumer
→
3 × curl /producer/…200, 200, 200
→
--describenenhum membro ativo · atraso 3
→
start consumerretoma no offset 2: a, b, c · atraso 0
  • O produtor não percebeu: respondeu 200 três vezes.
  • Com REST, essas três chamadas teriam falhado; com um log no meio, o consumidor alcança o atraso.

A mensageria assíncrona transforma "o outro serviço está fora do ar" de um erro em um atraso.

6 · Na loja: order-events

POST /orders
→
account, productREST, síncrono
→
salva o pedido
→
send(order-events, chave = id do pedido)
→
201
próximo poll
→
notification-servicesending confirmation email: order …
  • Publique depois de salvar: nunca anuncie um pedido que não existe.
  • O order-service nunca chama o notification-service e não espera o e-mail.

6 · O mesmo padrão, três mudanças

referência
loja
produtor
ProducerServicesend(topic, json)
OrderEventPublishersend("order-events", id, json): com chave
config
KafkaProducerConfig
a mesma classe, no pacote store.order
consumidor
consumer-service
notification-servicenovo pacote, grupo notification-group, tópico order-events
mensagem
{id, message}
{id, idAccount, total}
  • Teste: faça login, POST /orders → 201 na hora → a linha do e-mail em docker compose logs notification.

7 · Partições: a chave escolhe uma

order-servicechave = id do pedido
murmur2(chave) % 3 →
order-events · 3 partições
P0eventos de alguns pedidos, em ordem
P1…
P2…
→
notification-group
notification-1lê P0, P1
notification-2lê P2
  • Mesma chave → mesma partição → os eventos de um pedido ficam em ordem.
  • Num grupo, cada partição tem um leitor; entrar ou sair → rebalanceamento, retomando no offset confirmado.
  • O Kafka consegue acrescentar partições (--alter --partitions 3), nunca removê-las.

7 · Quantas instâncias ajudam?

1 instância
2
3
4
1 partição (o lab)
lê P0
1 ociosa
2 ociosas
3 ociosas
3 partições
lê as 3
P0, P1 · P2
uma cada
1 ociosa
  • O número de partições limita o paralelismo de um grupo.
  • docker compose up -d --scale notification=2 + kafka-consumer-groups --describe --members: #PARTITIONS 1 e 0.
  • Outro grupo (analytics) lê todas as mensagens, nos seus próprios offsets.

7 · Sem chave, as partições não espalham

9 × curl /producer/…sem chave
particionador sticky →
store-producer-example · 3 partições
P0nada novo
P1as nove: offsets 0 a 8
P2nada
→
grupo store
consumer-1lê P0, P1: faz todo o trabalho
consumer-2lê P2: ocioso
  • Sem chave → o produtor enche uma partição antes de passar à próxima (KIP-794, uma Kafka Improvement Proposal): lotes grandes, nada espalhado.
  • Uma chave espalha a carga e mantém cada chave em ordem: é por isso que order-events usa o id do pedido.

Simulador: partições e grupos

A parte da loja no lab, sem Docker: order-events com 1 partição, um notification-service. O play roda uma página; os botões funcionam a qualquer momento.

6 pedidos, 1 partiçãotodos em P0 · notification-2 não recebe nada
→
--partitions 3notification-1 ← P0, P1 · notification-2 ← P2
→
mais 6 pedidosdivididos em 2, 2 e 2 pela chave
  • Pare uma instância: a partição dela passa para a outra, que esvazia o atraso uma mensagem por poll.
  • Modo livre: 4 instâncias em 3 partições — uma fica ociosa.

Seção 7 da página · simulador order-events, roteiro "7 · Partições e grupos".

8.1 · At-least-once

registro no offset 0
→
e-mail enviado
→
morto antes do commit
→
reinício / rebalanceamentooffset 0 de novo
→
o mesmo e-mail duas vezes
  • O container confirma depois que o listener retorna: uma queda no meio significa reentrega.
  • O Kafka entrega pelo menos uma vez — o consumidor precisa ser idempotente.

Registre os ids de pedido notificados num armazenamento durável (INSERT … ON CONFLICT DO NOTHING) e envie o e-mail só quando o insert acrescentou uma linha. Um conjunto em memória morre justamente na queda que causa a reentrega.

8.2 · Uma mensagem que não pode ser processada

echo 'oops' | console producernão é JSON
→
readValue lança exceção10 tentativas, sem pausa
→
ERROR · Backoff … exhaustedfor order-events-0@1
→
confirma depois delaa mensagem sumiu
  • Sem error handler próprio → o DefaultErrorHandler do Spring Kafka: FixedBackOff(0, 9), registra, pula.
  • Nada trava — os próximos pedidos passam, atraso de volta a 0 — mas uma linha de log é tudo o que sobra.

Para um pedido cujo evento tinha um bug, é um cliente que nunca recebe o e-mail — e ninguém percebe.

8.3 · Um dead-letter topic (DLT)

registro ruim
→
3 tentativas, a 1 sRecord in retry and not yet recovered
→
DeadLetterPublishingRecoverer
→
order-events-dltoffset 0 · oops · inspecionar, corrigir, reprocessar
new DefaultErrorHandler(new DeadLetterPublishingRecoverer(kafkaTemplate(),
    (record, ex) -> new TopicPartition(record.topic() + "-dlt", -1)), new FixedBackOff(1000L, 2L))
  • Destino padrão: <tópico>-dlt, mesma partição → o DLT precisaria de tantas partições quanto o original; -1 deixa o Kafka escolher.
  • O registro no DLT leva headers: tópico, partição e offset originais e a exceção.

Simulador: falhas

duplicatas
kill antes do commit1 e-mail duplicado
→
consumidor idempotentea repetição é pulada
mensagem ruim
handler padrão10 tentativas, pulada · 1 perdida · atraso 0
→
dead-letter topic3 tentativas → order-events-dlt · 0 perdidas
  • Os contadores mostram: e-mails enviados, e-mails duplicados, atraso do grupo, mensagens perdidas, order-events-dlt.
  • Um registro por poll: cada passo da página é um clique.

Seção 8 da página · simulador order-events, roteiro "8 · Falhas".

Armadilhas

Sintoma Causa
401 / 404 em /producer/hello rota não aberta no RouterValidator / ausente no gateway
COPY target/*.jar falha mvn clean package não rodou nesse serviço
jar do consumidor chamado producer-service-1.0.0.jar o pom.xml copiado ainda tem o artifactId do produtor
uma segunda instância nunca trabalha 1 partição — ou sem chave: tudo numa partição
um e-mail enviado duas vezes queda antes do commit: torne o consumidor idempotente
um evento ruim sumiu o error handler padrão o pulou: acrescente um dead-letter topic

Pontos-chave

  1. Um tópico é um log: o produtor acrescenta e responde; os consumidores leem nos seus próprios offsets.
  2. Spring Kafka: KafkaTemplate.send para publicar, @KafkaListener + um grupo para consumir; o container confirma.
  3. Um consumidor fora do ar significa atraso, não erros: ele alcança.
  4. Partições limitam o paralelismo de um grupo; uma chave espalha a carga e mantém cada chave em ordem.
  5. A entrega é at-least-once: consumidores idempotentes, com um registro durável.
  6. Sem um dead-letter topic, uma mensagem ruim é tentada 10 vezes e se perde.

Roteiro: (1) por que não mais uma chamada REST; (2) o Kafka em modo KRaft no compose; (3) o producer-service e a rota no gateway; (4) o consumer-service; (5) rodar, olhar dentro do Kafka, parar o consumidor; (6) a loja: order-events e o notification-service; (7) partições, grupos, chaves; (8) duplicatas, mensagens ruins, o dead-letter topic; o simulador.

A tabela "Referência / Na loja" da página lista as mesmas peças: produtor, tópico, chave, consumidor, mensagem.

Medido na stack do lab: depois de --partitions 3 e de um restart, nove mensagens via curl foram todas para a partição 1.