Wzorzec transactional outbox

Wzorzec transactional outbox, nazywany też transakcyjną skrzynką nadawczą, służy do niezawodnego przekazywania zdarzeń między systemami. Problem pojawia się wtedy, gdy jedna akcja ma dwa skutki: trzeba zapisać zmianę w bazie danych i wysłać komunikat do kolejki, webhooka albo innej usługi. Jeżeli zapis kontaktu powiedzie się, lecz wysyłka zdarzenia nie, CRM ma dane, ale automatyzacja nie uruchomi wiadomości ani kolejnego kroku. Jeżeli najpierw wyślesz zdarzenie, a zapis się nie uda, drugi system dostanie informację o sprawie, która formalnie nie istnieje. AWS opisuje ten problem jako dual write.

Outbox zmienia kolejność odpowiedzialności. Aplikacja zapisuje dane biznesowe i rekord zdarzenia outbox w jednej transakcji, czyli w operacji, która kończy się w całości albo wcale. Rekord może zawierać identyfikator sprawy, typ zdarzenia, wersję danych i status publikacji. Dopiero osobny publisher odczytuje nieopublikowane rekordy i przekazuje je do brokera wiadomości lub API. Jeśli publisher chwilowo nie działa, informacja nadal leży przy danych źródłowych i może zostać wysłana później. Nie trzeba zgadywać na podstawie logów, czy zdarzenie w ogóle istniało.

Dla ekspertki sprzedającej produkt cyfrowy przykład jest prosty. Potwierdzona płatność ma zapisać zamówienie, nadać dostęp, dodać klientkę do odpowiedniego segmentu oraz wysłać onboarding. Krytyczne zdarzenie „zakup potwierdzony” powinno dostać trwały identyfikator przy zapisie zamówienia. Proces publikujący może potem przekazać je do workflow, który wykonuje dalsze kroki. Gdy platforma e-mailowa ma awarię, zakup pozostaje poprawnie zapisany, a komunikacja może zostać wznowiona. To lepsze niż ręczne odtwarzanie listy klientów na podstawie płatności.

Outbox nie daje automatycznie gwarancji dokładnie jednego dostarczenia. Publisher może wysłać komunikat, a następnie nie zdążyć oznaczyć go jako opublikowany przed awarią. Po restarcie wyśle go ponownie. Dlatego odbiorca musi być idempotentny: dwukrotne zdarzenie o tym samym identyfikatorze nie może utworzyć dwóch dostępów, dwóch faktur ani dwóch wiadomości. Przechowuj identyfikator zdarzenia po stronie odbiorcy albo użyj operacji upsert opartej na stabilnym identyfikatorze zamówienia. Outbox i idempotencja są parą, nie alternatywami.

W małej automatyzacji nie zawsze potrzebujesz budować pełny broker i własną tabelę outbox. Sens wzorca warto zastosować, gdy strata pojedynczego zdarzenia jest kosztowna, workflow dotyka płatności, dostępu lub zgód, albo kilka systemów musi zareagować na tę samą zmianę. W prostszym scenariuszu odpowiednikiem może być trwały rejestr zadań w bazie, kolejce albo narzędziu automation, o ile da się jednoznacznie sprawdzić status i ponowić wysyłkę. Nie wystarczy historia uruchomień bez identyfikatora biznesowego.

Projekt zacznij od rozdzielenia stanu biznesowego od skutków ubocznych. Wskaż, który zapis jest źródłem prawdy, jakie zdarzenie opisuje zmianę i kto publikuje je dalej. Ustal statusy takie jak pending, published i failed, czas ponowienia oraz sposób obsługi błędu po wielu próbach. Zapisuj payload potrzebny odbiorcy albo bezpieczny odnośnik do rekordu, ale nie kopiuj do niego niepotrzebnych danych osobowych. Kontrakt danych określa, co oznacza zdarzenie i jakie pola są wymagane.

Najczęstszy antywzorzec to wysłanie webhooka bezpośrednio po zapisie i założenie, że odpowiedź HTTP 200 zamyka sprawę. Taka odpowiedź może potwierdzać jedynie przyjęcie żądania, nie jego trwałe przetworzenie. Drugi błąd to ponawianie bez identyfikatora, które tworzy duplikaty. Zbuduj jeden test: zasymuluj awarię między zapisem a publikacją, potem uruchom publisher dwa razy. Jeżeli zdarzenie finalnie trafia do odbiorcy, a odbiorca wykonuje skutek dokładnie raz, proces ma podstawową odporność.