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
să creezi un topic cu partiții și să alegi cheia mesajelor
să trimiți mesaje JSON cu KafkaTemplate
să le primești cu @KafkaListener, în grupuri diferite
să tratezi un mesaj stricat cu reîncercări și dead letter topic
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ș.
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.
Linia 13. Orașul e „Sibiu”, nu e gol, deci if e sărit.
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ă.
Linia 17, alt mesaj. Vine RO101, din partiția 0. Același drum, fără eroare.
Linia 17, alt mesaj. RO104 are tot cheia „Cluj”, deci e tot în partiția 0, după RO101. Ordinea lor e garantată.
Linia 14, încercarea 1. RO105 are orașul gol. Metoda aruncă excepția, iar mesajul nu e confirmat. DefaultErrorHandler preia controlul.
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ă.
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”.
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.
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ă.
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.
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.
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:
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ă.
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:
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
Un topic are partiții; cheia alege partiția, iar ordinea e garantată doar în interiorul ei.
KafkaTemplate.send trimite, @KafkaListener primește; amândouă se configurează din spring.kafka.*.
Fiecare grup primește toate mesajele; într-un grup, partițiile se împart între instanțe.
Un mesaj care eșuează e reîncercat, apoi mutat în -dlt, ca să nu blocheze restul.
Î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.