Kafka minták ebben a projektben

Az újrahasználható Kafka-réteg a backend src/lib/kafka mappájában található. Ezek a minták szétválasztják az adatbázis-munkát, a publikálást és a fogyasztást. A terminológiához használd a Kafka alapokat.

Outbox

Az outbox a szándékolt eseményt az adatbázisban tárolja, mielőtt egy dispatcher publikálná. Ez szétválasztja a domain-írást a Kafka elérhetőségétől.

A normál sorrend a következő:

1. A domain-kód létrehoz egy outbox-sort.
2. A dispatcher atomikusan lefoglalja: PENDING -> DISPATCHING.
3. A sikeres publikálás lezárja: DISPATCHING -> PUBLISHED.
4. A fogyasztás UNDER_PROCESSING állapotba lép.
5. A feldolgozás SUCCESS vagy PUSHED_FAILURE állapotban ér véget.

A PREQUEUED állapot a munkát addig tartja, amíg ki nem adják a PENDING állapotba. A FAILURE a publikálási hiba útvonalát jelöli. A SUCCESS, a PUSHED_FAILURE és a FAILURE a szokásos átmeneti segédben végállapotok.

A consumer előrébb viheti az állapotot, mielőtt a publisher befejezi az adatbázis-visszaigazolást. Az átmeneti szerződés ezért a DISPATCHING állapotból is engedi a feldolgozást. A markPublished feltételes frissítést (compare-and-set) használ. Elfogadja, ha a feldolgozás már előrehaladt vagy sikeres végállapotba jutott, és nem állítja vissza az állapotot.

A stale dispatch-helyreállítás a topicot és a partíciót ellenőrzi, mielőtt eldöntené, hogy egy meglévő publikálást jelöljön meg vagy sorba állítson újra. Önmagában az időtúllépés nem bizonyítja, hogy semmi nem jutott el a Kafkába. Az ismeretlen partíció hibáinak külön, funkcióvezérelt helyreállítási útjuk van. Kerüld a kézi státuszszerkesztést.

Forrástérkép

Modul/függvény	Felelősség
src/lib/kafka/patterns/outbox/outbox-queue.ts	Tartós sorbanálló rekordok létrehozása
outbox-publisher.ts: claimPendingEventForDispatch	Atomikus PENDING-lefoglalás
outbox-publisher.ts: markPublished, markPublishFailed	Feltételes publikálás-lezárás
outbox-publisher.ts: requeueStaleDispatchingEvents	Elavult dispatch-munka ellenőrzése és helyreállítása
outbox-tracing.ts: transitionOutboxEventStatus, getOutboxEventStatus	Közös nyomkövetés és státuszelérés
outbox-status.ts	Engedélyezett átmenetek és végállapot-ellenőrzés
src/services/KafkaTester/modules/mailbox/processing	KafkaTester-feldolgozás és eredményállapot
src/services/KafkaTester/modules/runtime/kafka-tester.service.ts	All-in-one szolgáltatás-orchestráció

A fenti outbox-fájlnevek a src/lib/kafka/patterns/outbox/ mappában vannak.

Idempotencia

A src/lib/kafka/patterns/idempotency.ts a processKafkaMessageOnce függvényt valósítja meg. Egyedi azonosítója a consumerGroup + topic + partition + offset.

A függvény egy tranzakcióban szúrja be a ProcessedKafkaMessage rekordot, és hívja meg a work(tx) függvényt. Sikertelen tranzakció mindkettőt visszagörgeti. Egyedi kulcs-ütközés az already_processed értéket adja vissza. Más hibák tovább terjednek. A consumer kihagyja a végállapotú outbox-munkát. Ha az eredmény már feldolgozott, de a sikerállapot hiányos, a consumer pótolja a hiányzó sikeres átmenetet. A projekciós munkát nem ismétli meg.

Ez a rögzített tranzakciós hatásokat védi az adott offset-azonosítóhoz. Másik csoport vagy újra publikált rekord másik azonosítót kap. A külső hatásoknak saját idempotencia-szerződésük kell legyen.

Szekvenciális partícióhozzárendelés

A src/lib/kafka/patterns/sequential-partition.ts partíciót foglal le felhasználó létrehozásakor. A MAX_USERS_PER_QueProcessor_PARTITION értéket használja, szükség esetén új hozzárendelést hoz létre, és az admin kliensen keresztül szinkronizálja a broker partíciószámát.

Kulcs és explicit partíció

A publikálás tartalmazza a key = String(userId) értéket és a felhasználó hozzárendelt partícióját. Így az adott felhasználó rendezett mailbox-sorrendje a tartós útvonalán marad. Tartsd meg együtt az adatbázis-leképezést és a broker-elrendezést.

A normál mailbox-parancsok a kanonikus mailbox-felhasználói azonosítót használják, nem a böngészőben bejelentkezett szereplőt. Ne cseréld le megjelenített e-mail címre vagy Better Auth azonosítóra. Lásd az azonosító-fogalmakat.