MyCodeSchool

Pasul 1 din 5

Spring Boot

Pasul 1 din 5 · Ce construiești

  • Spring Boot
  • Avansat
  • 15 minute

Primii pași cu Apache Kafka în Spring Boot

O firmă de curierat anunță fiecare colet expediat. Depozitul îl sortează, un serviciu de SMS anunță clientul, iar niciunul nu știe de celălalt: comunică doar prin Kafka. Așa arată când rulează:

ieșirea aplicației, rulare reală
SMS: coletul RO102 a plecat
SMS: coletul RO101 a plecat
SMS: coletul RO104 a plecat
SMS: coletul RO105 a plecat
SMS: coletul RO103 a plecat
Depozit: RO102 spre Sibiu, partiția 1
Depozit: RO101 spre Cluj, partiția 0
Depozit: RO104 spre Cluj, partiția 0
Respins: RO105 (Listener method 'void ro.exemplu.colete.Depozit.primeste(ro.exemplu.colete.Colet,int)' threw exception; Colet fără oraș: RO105)
Depozit: RO103 spre Brașov, partiția 2

La pornire, aplicația trimite cinci colete. Ultimul n-are oraș: depozitul îl încearcă de trei ori, apoi îl pune deoparte, într-un topic separat. Ordinea liniilor nu e cea a trimiterii, și vei vedea de ce.

Ai nevoie de un broker Kafka. Cel mai simplu, în Docker; imaginea oficială pornește un singur nod, gata de folosit pe portul 9092:

terminal
docker run -d --name kafka -p 9092:9092 apache/kafka:3.9.1

Pasul 2 din 5

Urmărește depozitul

Consumatorul din grupul depozit primește mesajele unul câte unul. Apasă pe „Linia următoare” și urmărește fiecare colet, inclusiv pe cel fără oraș.

Depozit.java
package ro.exemplu.colete;import org.springframework.kafka.annotation.KafkaListener;import org.springframework.kafka.support.KafkaHeaders;import org.springframework.messaging.handler.annotation.Header;import org.springframework.stereotype.Component;@Componentclass Depozit {    @KafkaListener(topics = "colete", groupId = "depozit")    void primeste(Colet c,            @Header(KafkaHeaders.RECEIVED_PARTITION) int p) {        if (c.oras().isBlank()) {            throw new IllegalArgumentException(                    "Colet fără oraș: " + c.awb());        }        System.out.println("Depozit: " + c.awb()                + " spre " + c.oras() + ", partiția " + p);    }}

Mesajul curent

Ce afișează depozitul


      

  1. Linia 11. Sosește primul mesaj, din partiția 1. JsonDeserializer a transformat deja textul JSON într-un Colet, iar @Header scoate numărul partiției din metadatele mesajului.
  2. Linia 13. Orașul e „Sibiu”, nu e gol, deci if e sărit.
  3. Linia 17. Se afișează coletul. Când metoda se termină fără excepție, Spring confirmă mesajul: offsetul grupului depozit pe partiția 1 avansează.
  4. Linia 17, alt mesaj. Vine RO101, din partiția 0. Același drum, fără eroare.
  5. Linia 17, alt mesaj. RO104 are tot cheia „Cluj”, deci e tot în partiția 0, după RO101. Ordinea lor e garantată.
  6. Linia 14, încercarea 1. RO105 are orașul gol. Metoda aruncă excepția, iar mesajul nu e confirmat. DefaultErrorHandler preia controlul.
  7. Linia 14, încercarea 3. Handlerul așteaptă o secundă și reîncearcă, de două ori, cum cere FixedBackOff(1000, 2). Datele nu se repară singure, deci toate trei încercările eșuează.
  8. După încercări. DeadLetterPublishingRecoverer copiază mesajul în topicul colete-dlt, cu motivul în antete. Consumatorul Respinse îl citește de acolo și afișează rândul cu „Respins”.
  9. Linia 17, abia acum. RO103 stătea în partiția 2 de la început. Același fir de execuție citea toate partițiile, iar cât timp reîncerca RO105, nu s-a ocupat de altceva.
  10. Gata. Toate mesajele au fost confirmate, inclusiv RO105, care a ajuns în DLT. Aplicația rămâne pornită și ascultă în continuare.

Prezice ieșirea

Trimiți, în ordine, RO201 și RO202, amândouă spre Cluj, fără alte mesaje. Ce afișează depozitul?

Răspuns: RO201, apoi RO202, din partiția 0.

Aceeași cheie, „Cluj”, dă mereu aceeași partiție. Într-o partiție, mesajele se citesc exact în ordinea în care au fost scrise.

Pasul 3 din 5

Cum circulă mesajele

Patru idei, fiecare cu fișierul ei din proiect. La final, două erori care par misterioase până le vezi o dată.

Topic, partiții și cheie

ColeteApp.java
package ro.exemplu.colete;import org.apache.kafka.clients.admin.NewTopic;import org.springframework.boot.SpringApplication;import org.springframework.boot.autoconfigure.SpringBootApplication;import org.springframework.context.annotation.Bean;import org.springframework.kafka.config.TopicBuilder;import org.springframework.kafka.core.KafkaTemplate;import org.springframework.kafka.listener.*;import org.springframework.util.backoff.FixedBackOff;@SpringBootApplicationpublic class ColeteApp {    public static void main(String[] args) {        SpringApplication.run(ColeteApp.class, args);    }    @Bean    NewTopic colete() {        return TopicBuilder.name("colete")                .partitions(3)                .build();    }    @Bean    NewTopic coleteDlt() {        return TopicBuilder.name("colete-dlt")                .partitions(3)                .build();    }    @Bean    DefaultErrorHandler erori(            KafkaTemplate<Object, Object> kafka) {        return new DefaultErrorHandler(                new DeadLetterPublishingRecoverer(kafka),                new FixedBackOff(1000, 2));    }}

Un topic e un jurnal de mesaje cu nume, aici colete. Îl împarți în partiții ca mai mulți consumatori să lucreze în paralel. Bean-urile NewTopic îi cer lui Spring să creeze topicurile la pornire, dacă lipsesc.

Cheia decide partiția: Kafka calculează un hash din ea. În rularea noastră, „Cluj” a ajuns în partiția 0, „Sibiu” în 1, „Brașov” în 2. Ordinea e garantată doar în interiorul unei partiții, de aceea cheia e orașul: coletele spre același oraș rămân în ordine.

Producătorul: KafkaTemplate

Expeditor.java
package ro.exemplu.colete;import org.springframework.kafka.core.KafkaTemplate;import org.springframework.stereotype.Service;@Serviceclass Expeditor {    private final KafkaTemplate<String, Colet> kafka;    Expeditor(KafkaTemplate<String, Colet> kafka) {        this.kafka = kafka;    }    void trimite(Colet c) {        kafka.send("colete", c.oras(), c);    }}

send(topic, cheie, valoare) pune mesajul într-un buffer și se întoarce imediat; trimiterea efectivă are loc în fundal. Metoda întoarce un CompletableFuture, pe care îl poți aștepta dacă vrei să știi sigur că mesajul a ajuns la broker.

KafkaTemplate e creat de auto-configurarea lui Spring Boot, pe baza cheilor spring.kafka.*. Expeditorul nu știe cine va citi coletele.

Consumer groups

Sms.java
package ro.exemplu.colete;import org.springframework.kafka.annotation.KafkaListener;import org.springframework.stereotype.Component;@Componentclass Sms {    @KafkaListener(topics = "colete", groupId = "sms")    void anunta(Colet c) {        System.out.println("SMS: coletul " + c.awb()                + " a plecat");    }}

Fiecare grup primește toate mesajele topicului și își ține propriul offset, adică „până unde am citit”. De aceea SMS-ul a anunțat și RO105, pe care depozitul l-a respins.

În interiorul unui grup, partițiile se împart între instanțe. Pornești aplicația de trei ori și fiecare instanță primește câte o partiție. Offseturile salvate se văd cu unealta din imaginea Kafka:

kafka-consumer-groups.sh --describe --group depozit
GROUP    TOPIC   PARTITION  CURRENT-OFFSET  LOG-END-OFFSET  LAG
depozit  colete  1          1               1               0
depozit  colete  0          3               3               0
depozit  colete  2          1               1               0

LAG 0 înseamnă că grupul a citit tot. Partiția 0 are trei mesaje: RO101, RO104 și RO105, a cărui cheie goală a ajuns tot acolo. Am scos coloanele goale, care apar când aplicația e oprită.

JSON, reîncercări și DLT

application.properties
spring.main.banner-mode=offlogging.level.root=warnspring.kafka.bootstrap-servers=localhost:9092spring.kafka.producer.value-serializer=\  org.springframework.kafka.support.serializer.JsonSerializerspring.kafka.consumer.value-deserializer=\  org.springframework.kafka.support.serializer.JsonDeserializerspring.kafka.consumer.properties.spring.json.trusted.packages=\  ro.exemplu.coletespring.kafka.consumer.auto-offset-reset=earliest

Kafka transportă doar octeți. JsonSerializer transformă Colet în JSON și adaugă un antet cu numele clasei; JsonDeserializer reface obiectul, dar numai pentru pachetele declarate de încredere.

Bean-ul DefaultErrorHandler din ColeteApp e preluat automat de Boot. După reîncercări, DeadLetterPublishingRecoverer mută mesajul în colete-dlt, numele implicit: topicul original plus -dlt. Acolo îl citește Respinse:

Respinse.java
package ro.exemplu.colete;import org.springframework.kafka.annotation.KafkaListener;import org.springframework.kafka.support.KafkaHeaders;import org.springframework.messaging.handler.annotation.Header;import org.springframework.stereotype.Component;@Componentclass Respinse {    @KafkaListener(topics = "colete-dlt", groupId = "respinse")    void verifica(Colet c,            @Header(KafkaHeaders.DLT_EXCEPTION_MESSAGE)            String motiv) {        System.out.println("Respins: " + c.awb()                + " (" + motiv + ")");    }}

Capcană: brokerul nu e unde crezi

Containerul e oprit sau portul e greșit. Aplicația nu se oprește cu o eroare clară, ci repetă același avertisment, de mai multe ori pe secundă:

WARN … [AdminClient clientId=adminclient-1] Connection to node -1 (localhost/127.0.0.1:9093) could not be established. Node may not be available.

Repară verificând docker ps și cheia spring.kafka.bootstrap-servers: aici era 9093 în loc de 9092.

Capcană: pachetul care nu e de încredere

Uiți cheia spring.json.trusted.packages sau scrii alt pachet. Mesajul nu poate fi citit, nu e confirmat și e citit iar, la nesfârșit. Într-o rulare de 20 de secunde, jurnalul a ajuns la peste 22 de milioane de rânduri:

Caused by: org.apache.kafka.common.errors.RecordDeserializationException: Error deserializing VALUE for partition colete-1 at offset 1. If needed, please seek past the record to continue consumption.
Caused by: java.lang.IllegalArgumentException: The class 'ro.exemplu.colete.Colet' is not in the trusted packages: [java.util, java.lang]. …

Repară scriind pachetul clasei tale în spring.json.trusted.packages, ca în cardul 4.

Pasul 4 din 5

Verifică-te

Cinci întrebări noi. După fiecare răspuns vezi imediat de ce e așa.

1 din 5 · Alege varianta

Aplicația trimite 5 colete. Câte primește grupul sms?

Răspuns: toate 5.

Fiecare grup citește topicul întreg, independent. Ce face depozitul cu un mesaj nu schimbă nimic pentru SMS.

2 din 5 · Alege varianta

Topicul are 3 partiții. Pornești 4 instanțe ale aplicației, toate în grupul depozit. Ce se întâmplă?

Răspuns: trei lucrează, a patra stă.

O partiție aparține unei singure instanțe din grup. Numărul de partiții e limita de paralelism a grupului; a patra instanță preia o partiție doar dacă alta cade.

3 din 5 · Prezice ieșirea

Schimbi în Expeditor linia în kafka.send("colete", c.awb(), c), deci cheia devine AWB-ul. Ce garanție pierzi?

Răspuns: ordinea pe oraș.

Fiecare AWB e diferit, deci coletele spre Cluj se pot împrăștia în partiții diferite și pot fi procesate în altă ordine. Mesajele ajung toate, doar ordinea între ele nu mai e sigură.

4 din 5 · Alege varianta

Schimbi politica în cea de mai jos. De câte ori rulează în total metoda primeste pentru un colet fără oraș?

ColeteApp.java, fragment
new FixedBackOff(500, 4)

Răspuns: 5.

Primul argument e pauza în milisecunde, al doilea numărul de reîncercări. O încercare inițială plus 4 reîncercări fac 5 rulări, apoi mesajul merge în colete-dlt.

5 din 5 · Alege varianta

De ce s-a afișat RO103 abia după ce RO105 a ajuns în DLT, deși era în altă partiție?

Răspuns: consumatorul era ocupat.

RO103 a fost trimis al treilea. Grupul avea o singură instanță, cu un singur fir, iar pauzele dintre reîncercări au blocat tot. Cu mai multe instanțe, partiția 2 ar fi fost citită în paralel.

Pasul 5 din 5

Ce ai învățat

Încearcă singur

Pornește brokerul din pasul 1, copiază cele șapte fișiere din lecție într-un proiect cu „Spring for Apache Kafka” și rulează aplicația. Apoi pornește a doua instanță și urmărește, cu kafka-consumer-groups.sh, cum își împart partițiile.

Continuă cu