Dane na zewnątrz vs wewnątrz — lekcje Pata Hellanda dla aplikacji

Co oznacza „na zewnątrz vs wewnątrz” prostymi słowami

Kiedy budujesz aplikację, łatwo wyobrazić sobie żądania przychodzące ładnie, jedno po drugim, w odpowiedniej kolejności. Sieci w rzeczywistości tak nie działają. Użytkownik naciska „Pay” dwa razy, bo ekran się zawiesił. Połączenie mobilne znika zaraz po naciśnięciu przycisku. Webhook przychodzi późno albo dwa razy. Czasem w ogóle nie przyjdzie.

Pomysł Pata Hellanda o danych na zewnątrz vs wewnątrz to przejrzawy sposób myślenia o tym bałaganie.

Jak wygląda „na zewnątrz"

„Na zewnątrz” to wszystko, czego twój system nie kontroluje. To miejsca, gdzie rozmawiasz z innymi ludźmi i systemami, i gdzie dostarczenie jest niepewne: żądania HTTP z przeglądarek i aplikacji mobilnych, komunikaty z kolejek, webhooki stron trzecich (płatności, e‑mail, wysyłka) oraz ponowienia wyzwalane przez klientów, proxy lub zadania w tle.

Na zewnątrz zakładaj, że komunikaty mogą być opóźnione, powielone lub przyjść poza kolejnością. Nawet jeśli coś jest „zwykle niezawodne”, projektuj pod kątem dnia, kiedy takie nie będzie.

Co oznacza „wewnątrz"

„Wewnątrz” to to, co twój system potrafi uczynić zależnym. To trwały stan, który przechowujesz, reguły, które egzekwujesz, i fakty, które możesz później udowodnić:

• Rekordy w bazie danych i ich historia
• Reguły biznesowe (np.: „zamówienie można opłacić tylko raz”)
• Źródło prawdy dla statusu (pending, paid, canceled)

Wewnątrz chronisz inwarianty. Jeśli obiecujesz „jedna płatność na zamówienie”, ta obietnica musi być wymuszana wewnątrz, bo na zewnątrz nie można ufać, że wszystko zachowa się poprawnie.

Zmiana sposobu myślenia jest prosta: nie zakładaj idealnego dostarczenia ani idealnego czasu. Traktuj każdą interakcję z zewnątrz jako zawodną sugestię, która może się powtórzyć, i spraw, by wnętrze reagowało bezpiecznie.

To ma znaczenie nawet dla małych zespołów i prostych aplikacji. Pierwsza awaria sieci, która stworzy podwójne obciążenie lub zablokowane zamówienie, przestaje być teorią i staje się zwrotem, ticketem do supportu i utratą zaufania.

Konkretny przykład: użytkownik klika „Place order”, aplikacja wysyła żądanie i połączenie przerywa. Użytkownik próbuje ponownie. Jeśli wewnątrz nie ma sposobu na rozpoznanie „to ta sama próba”, możesz utworzyć dwa zamówienia, zarezerwować towar dwukrotnie lub wysłać dwa potwierdzenia e‑mail.

Kluczowa lekcja od Pata Hellanda

Punkt Hellanda jest prosty: świat zewnętrzny jest niepewny, ale wnętrze systemu musi pozostać spójne. Sieci gubią pakiety, telefony tracą zasięg, zegary się rozjeżdżają, a użytkownicy naciskają odśwież. Twoja aplikacja nie może tego kontrolować. Może jednak kontrolować to, co przyjmuje za „prawdę”, gdy dane przekroczą jasną granicę.

Czas i niepewność w codziennej chwili

Wyobraź sobie kogoś zamawiającego kawę na telefonie, przechodzącego przez budynek z kiepskim Wi‑Fi. Naciska „Pay”. Pojawia się spinner. Sieć się rozłącza. Kliknie ponownie.

Może pierwsze żądanie dotarło do serwera, ale odpowiedź nigdy do klienta nie wróciła. Albo może żadne żądanie nie dotarło. Z punktu widzenia użytkownika obie możliwości wyglądają tak samo.

To jest czas i niepewność: jeszcze nie wiesz, co się stało, i możesz dowiedzieć się później. Twój system musi zachowywać się rozsądnie, czekając na wyjaśnienie.

Ponowienia, duplikaty i przestawienia kolejności

Gdy zaakceptujesz, że zewnętrze jest zawodliwe, kilka „dziwnych” zachowań staje się normalnych:

• Ponowienia tworzą duplikaty (dwa żądania „Pay”).
• Wiadomości przychodzą poza kolejnością (np. „cancel” przed „pay”).
• Żądanie zostało przetworzone, ale klient nigdy nie zobaczył odpowiedzi.

Dane z zewnątrz to roszczenie, nie fakt. „Zapłaciłem” to tylko stwierdzenie wysłane przez zawodny kanał. Staje się faktem dopiero, gdy zapiszesz je wewnątrz systemu w sposób trwały i spójny.

To skłania do trzech praktycznych nawyków: zdefiniuj jasne granice, zabezpiecz ponowienia poprzez idempotencję i zaplanuj rekoncyliację, gdy rzeczywistość się nie zgadza.

Jasne granice: co twój system posiada, a czego nie

Pomysł „na zewnątrz vs wewnątrz” zaczyna się od praktycznego pytania: gdzie zaczyna się i kończy prawda twojego systemu?

Wewnątrz granicy możesz dawać silne gwarancje, bo kontrolujesz dane i reguły. Na zewnątrz robisz najlepsze próby i zakładasz, że wiadomości mogą zginąć, zostać powielone, opóźnione lub przyjść poza kolejnością.

W rzeczywistych aplikacjach granica często pojawia się w miejscach takich jak:

• Punkt końcowy API, który zapisuje rekord do bazy danych
• Konsument kolejki, który zamienia zdarzenie w trwałą zmianę
• Handler callbacku, który zapisuje, co powiedział dostawca
• Nadawca, który powiadamia inny system po zatwierdzeniu własnego stanu

Gdy narysujesz tę linię, zdecyduj, które inwarianty są niepodważalne wewnątrz. Przykłady:

• ID zamówienia jest unikalne w bazie danych.
• Saldo nigdy nie spada poniżej zera.
• Stan przechodzi tylko do przodu (utworzone -> opłacone -> wysłane).
• Każde zewnętrzne żądanie, które akceptujesz, ma zarejestrowaną ścieżkę audytu.

Granica potrzebuje też jasnego języka opisującego „gdzie jesteśmy”. Wiele błędów żyje w luki między „usłyszeliśmy” a „skończyliśmy”. Pomocny wzorzec to oddzielenie trzech znaczeń:

• Received: wiadomość dotarła do krawędzi (niekoniecznie jeszcze zapisana)
• Accepted: zapisałeś ją i możesz bezpiecznie ponawiać pracę później
• Processed: zamierzone zadanie zakończyło się i zapisałeś wynik

Gdy zespoły to pominą, dostają błędy, które pojawiają się tylko pod obciążeniem lub podczas częściowych awarii. Jeden system używa „paid” na oznaczenie pobrania pieniędzy; inny używa go jako rozpoczęcia próby płatności. Taka niezgodność tworzy duplikaty, zablokowane zamówienia i bilety, których nikt nie potrafi odtworzyć.

Idempotencja: zabezpieczenie ponowień

Idempotencja oznacza: jeśli to samo żądanie zostanie wysłane dwukrotnie, system potraktuje je jak jedno i zwróci ten sam wynik.

Ponowienia są normalne. Timeouty się zdarzają. Klienci się powtarzają. Jeśli zewnętrze może się powtarzać, twoje wnętrze musi zamienić to w stabilne zmiany stanu.

Prosty przykład: aplikacja mobilna wysyła „pay $20” i połączenie ginie. Aplikacja ponawia. Bez idempotencji klient może zostać obciążony dwa razy. Z idempotencją drugie żądanie zwraca wynik pierwszego obciążenia.

Powszechne sposoby implementacji idempotencji

Większość zespołów używa jednego z tych wzorców (czasem mieszanych):

• Idempotency key: klient wysyła unikalny klucz dla planowanej akcji (np. Idempotency-Key: ...). Serwer zapisuje klucz i ostateczną odpowiedź.
• Tabela deduplikacji: przechowaj wiersz indeksowany po (client_id, key) lub (order_id, operation) i odmów wykonania efektu ubocznego drugi raz.
• Klucze naturalne: użyj identyfikatora biznesowego, który jest już unikalny, więc „create payment” może istnieć tylko raz.

Gdy przychodzi duplikat, najlepszym zachowaniem zwykle nie jest „409 conflict” ani ogólny błąd. To zwrócenie tego samego rezultatu, co za pierwszym razem, łącznie z tym samym ID zasobu i statusem. To sprawia, że ponowienia są bezpieczne dla klientów i zadań w tle.

Gdzie trzymać rekord (i jak długo)

Rekord idempotencji musi żyć wewnątrz twojej granicy w trwałym magazynie, nie w pamięci. Jeśli API się zrestartuje i zapomni, gwarancja bezpieczeństwa znika.

Przechowuj rekordy wystarczająco długo, by pokryć realistyczne ponowienia i opóźnione dostawy. Okno zależy od ryzyka biznesowego: minuty–godziny dla niskoryzykownych tworzeń, dni dla płatności/e‑maili/wysyłek gdzie duplikaty kosztują, i dłużej, jeśli partnerzy mogą ponawiać przez dłuższy czas.

Jak unikać pułapek „transakcji rozproszonych"

Transakcje rozproszone brzmią kojąco: jeden duży commit przez usługi, kolejki i bazy. W praktyce często są nieosiągalne, wolne lub zbyt kruche, by na nich polegać. Gdy w grę wchodzi skok sieciowy, nie możesz zakładać, że wszystko zatwierdzi się razem.

Typowa pułapka to budowanie workflowu, który działa tylko wtedy, gdy każdy krok powiedzie się od razu: zapisz zamówienie, obciąż kartę, zarezerwuj magazyn, wyślij potwierdzenie. Jeśli krok 3 timeoutuje, czy się powiódł czy nie? Jeśli ponowisz, czy podwójnie obciążysz lub podwójnie zarezerwujesz?

Dwa praktyczne podejścia to:

• Outbox/inbox: zapisz trwałą intencję w swojej bazie (wiersz outbox) w tej samej transakcji co zmiana stanu, a potem worker wyśle wiadomość. Po stronie odbiorcy trzymaj inbox indeksowany po ID wiadomości, żeby obsługa była bezpieczna przy ponownym dostarczeniu.
• Kroki w stylu sagi z kompensacjami: podziel workflow na mniejsze kroki, które kończą się niezależnie. Jeśli późniejszy krok zawiedzie, wykonaj kompensację (np. zwolnij rezerwację lub anuluj nieopłacone zamówienie), zamiast próbować cofać historię.

Wybierz jeden styl dla danego workflowu i trzymaj się go. Mieszanie „czasem outbox” z „czasem zakładamy sukces synchroniczny” tworzy trudne do przetestowania przypadki brzegowe.

Prosta zasada: jeśli nie możesz atomowo commitować przez granice, projektuj pod kątem ponowień, duplikatów i opóźnień.

Rekoncyliacja: jak rzeczywiste systemy naprawiają rozbieżności

Rekoncyliacja to przyznanie podstawowej prawdy: gdy twoja aplikacja rozmawia z innymi systemami przez sieć, czasem będziecie się nie zgadzać co do tego, co się stało. Żądania timeoutują, callbacki przychodzą późno, a ludzie powtarzają akcje. Rekoncyliacja to sposób wykrywania rozbieżności i naprawiania ich w czasie.

Traktuj zewnętrzne systemy jako niezależne źródła prawdy. Twoja aplikacja prowadzi własny wewnętrzny rejestr, ale potrzebuje sposobu porównania tego rejestru z tym, co dostawcy, partnerzy i użytkownicy faktycznie zrobili.

Powszechne mechanizmy rekoncyliacji

Większość zespołów używa kilku prostych narzędzi (prostota jest zaletą): worker, który ponawia zaległe akcje i ponownie sprawdza zewnętrzny status, harmonogram skanu wyszukujący niespójności oraz prosta akcja naprawcza dla supportu, by spróbować ponownie, anulować lub oznaczyć jako sprawdzone.

Co porównywać i co zapisywać

Rekoncyliacja działa tylko wtedy, gdy wiesz, co porównywać: wewnętrzny ledger vs ledger dostawcy (płatności), stan zamówienia vs stan wysyłki (fulfillment), stan subskrypcji vs stan billingowy.

Uczyń stany naprawialnymi. Zamiast przeskakiwać od „created” do „completed”, używaj stanów pośrednich typu pending, on hold lub needs review. Dzięki temu można bezpiecznie powiedzieć „nie jesteśmy pewni” i dać rekoncyliacji miejsce do lądowania.

Zachowuj mały ślad audytu przy ważnych zmianach:

• Kiedy wysłano żądanie i kiedy ostatnio otrzymano odpowiedź
• ID korelacji łączące twój rekord z zewnętrznym zdarzeniem/referencją
• Ostatni znany zewnętrzny status (i skąd pochodzi)
• Pole z powodem dla ręcznych nadpisów (kto, co, dlaczego)

Przykład: jeśli twoja aplikacja poprosiła o etykietę wysyłkową i sieć padła, możesz mieć „brak etykiety” wewnętrznie, podczas gdy przewoźnik faktycznie ją stworzył. Worker rekonsyliacyjny może wyszukać po ID korelacji, odkryć, że etykieta istnieje i posunąć zamówienie dalej (albo oznaczyć do przeglądu, jeśli dane się nie zgadzają).

Krok po kroku: projektowanie workflowu odpornego na awarie sieci

Gdy założysz, że sieć zawiedzie, cel się zmienia. Nie chodzi o to, by każdy krok za każdym razem się powiódł. Chodzi o to, żeby każdy krok był bezpieczny do powtórzenia i łatwy do naprawienia.

Praktyczny workflow

1. Napisz jednozdaniowe stwierdzenie granicy. Bądź konkretny, co twój system posiada (źródło prawdy), co tylko odwzorowuje, a co tylko żąda od innych.

2. Wypisz tryby awarii przed happy path. Przynajmniej: timeouty (nie wiesz, czy zadziałało), duplikaty żądań, częściowy sukces (jeden krok się powiódł, kolejny nie), i zdarzenia poza kolejnością.

3. Wybierz strategię idempotencji dla każdego wejścia. Dla synchronicznych API to często klucz idempotencji + zapisany wynik. Dla komunikatów/zdarzeń zwykle unikalne ID wiadomości i rekord „czy przetworzyłem to?”.

4. Zapisz intencję, potem działaj. Najpierw przechowaj coś trwałego, np. PaymentAttempt: pending lub ShipmentRequest: queued, potem wykonaj wywołanie zewnętrzne, potem zapisz wynik. Zwróć stabilne ID referencyjne, żeby ponowienia wskazywały na tę samą intencję, zamiast tworzyć nową.

5. Zbuduj rekoncyliację i ścieżkę naprawczą, i udostępnij je. Rekoncyliacja może być zadaniem, które skanuje „pending za długo” i ponownie sprawdza status. Ścieżka naprawcza to bezpieczna akcja administracyjna: „retry”, „cancel” lub „mark resolved”, z notatką audytu. Dodaj podstawową obserwowalność: ID korelacji, jasne pola statusu i kilka liczników (pending, retries, failures).

Przykład: jeśli checkout timeoutuje zaraz po wywołaniu dostawcy płatności, nie zgaduj. Zapisz próbę, zwróć ID próby i pozwól użytkownikowi ponowić z tym samym kluczem idempotencji. Później rekoncyliacja potwierdzi, czy dostawca obciążył, i zaktualizuje próbę bez podwójnego obciążenia.

Przykładowy scenariusz: przepływ zamówienia z ponowieniami i opóźnionymi callbackami

Klient naciska „Place order”. Twoja usługa wysyła żądanie płatności do dostawcy, ale sieć jest niestabilna. Dostawca ma własną prawdę, a twoja baza ma swoją. Będą dryfować, jeśli ich nie zaprojektujesz do tego.

Co dzieje się na zewnątrz (zdarzenia, których nie kontrolujesz)

Z twojej perspektywy zewnętrze to strumień komunikatów, które mogą być późne, powtarzane lub brakujące:

• „Submit order” dociera do twojego API.
• Twoje żądanie płatności idzie do dostawcy.
• Dostawca wysyła webhook „authorized”.
• Dostawca ponawia webhook i wysyła ten sam callback ponownie.
• Twój klient timeoutuje i ponawia „Place order”.

Żaden z tych kroków nie gwarantuje „exactly once”. Gwarantują raczej „może”.

Co przechowujesz wewnątrz (rekordy, które kontrolujesz)

Wewnątrz granicy przechowuj trwałe fakty i minimum potrzebne do powiązania zewnętrznych zdarzeń z tymi faktami.

Gdy klient pierwszy raz składa zamówienie, utwórz rekord order w jasnym stanie, np. pending_payment. Stwórz też rekord payment_attempt z unikalnym referencem dostawcy oraz idempotency_key powiązanym z akcją klienta.

Jeśli klient timeoutuje i ponawia, twoje API nie powinno tworzyć drugiego zamówienia. Powinno wyszukać idempotency_key i zwrócić ten sam order_id i aktualny stan. Ten prosty wybór zapobiega duplikatom przy awariach sieci.

Teraz webhook przychodzi dwukrotnie. Pierwszy callback aktualizuje payment_attempt do authorized i przechodzi zamówienie do paid. Drugi callback trafia do tego samego handlera, ale wykrywasz, że już przetworzyłeś to zdarzenie dostawcy (przez zapisanie ID zdarzenia dostawcy albo kontrolę bieżącego stanu) i nic nie robisz. Nadal możesz odpowiedzieć 200 OK, bo rezultat jest już prawdziwy.

Na końcu rekoncyliacja zajmuje się trudnymi przypadkami. Jeśli zamówienie jest nadal pending_payment po upływie czasu, zadanie w tle pyta dostawcę po zapisanym referencu. Jeśli dostawca mówi „authorized”, ale przegapiłeś webhook, aktualizujesz swoje rekordy. Jeśli dostawca mówi „failed”, a ty oznaczyłeś jako opłacone, flagujesz to do przeglądu lub wyzwalasz kompensacyjną akcję, np. zwrot.

Typowe błędy prowadzące do duplikatów i zablokowanych stanów

Większość duplikatów i „zawieszonych” workflowów wynika z mieszania tego, co stało się na zewnątrz (żądanie dotarło, wiadomość została odebrana) z tym, co bezpiecznie zatwierdziłeś wewnątrz.

Klasyczna awaria: klient wysyła „place order”, serwer zaczyna pracę, sieć pada, klient ponawia. Jeśli traktujesz każde ponowienie jak nową prawdę, dostaniesz podwójne obciążenia, zdublowane zamówienia lub wiele maili.

Zwykłe przyczyny:

• Zaufanie przychodzącemu żądaniu zbyt wcześnie: wysyłanie e‑maili lub logowanie „zamówienie utworzone” zanim commit do bazy będzie trwały.
• Ponowienia tworzą nowe wiersze: generowanie nowego ID zamówienia przy każdej próbie zamiast mapowania ponowień na jeden rezultat.
• Zakładanie „exactly once”: kolejki i callbacki tego nie gwarantują. Duplikaty, opóźnienia i przestawienia kolejności się zdarzają.
• Brak stabilnych identyfikatorów: jeśli nie możesz odpowiedzieć na pytanie „czy widziałem tę intencję wcześniej?”, nie możesz zapobiec duplikatom.
• Tylko success/failure, brak stanu pośredniego: bez pending/awaiting, timeouty stają się tajemnicą, a użytkownicy klikają ponownie.

Jedno zagadnienie pogarsza wszystko: brak śladu audytu. Jeśli nadpisujesz pola i zostawiasz tylko ostatni stan, tracisz dowody potrzebne do późniejszej rekoncyliacji.

Dobry test zdrowego rozsądku to: „Jeśli uruchomię ten handler dwa razy, czy dostanę ten sam rezultat?” Jeśli odpowiedź brzmi nie, duplikaty nie są rzadkim przypadkiem. Są gwarantowane.

Szybka lista kontrolna i praktyczne kolejne kroki

Jeśli zapamiętasz jedną rzecz: twoja aplikacja musi być poprawna nawet wtedy, gdy wiadomości przyjdą późno, przyjdą dwa razy lub wcale nie przyjdą.

Użyj tej listy, by znaleźć słabe punkty zanim zamienią się w zdublowane rekordy, brakujące aktualizacje lub zablokowane workflowy:

• Źródło prawdy jest jawne: dla każdego workflowu potrafisz wskazać jedno miejsce, które jest „prawdą” (zazwyczaj twoja baza danych).
• Każdy zapis można bezpiecznie ponowić: każde polecenie/API ma klucz idempotencji (lub naturalny unikalny klucz).
• Stabilne ID i ID korelacji na całej ścieżce: potrafisz prześledzić jedną akcję biznesową przez logi, tabele i callbacki.
• Rekoncyliacja działa automatycznie: regularnie porównujesz „co my myślimy” vs „co się stało” i naprawiasz lub podnosisz alarm.
• Rollback nie korumpuje stanu: zmiany stanu są audytowalne i kompatybilne między wersjami.

Jeśli nie potrafisz szybko odpowiedzieć na jedno z tych pytań, to użyteczna wskazówka. Zazwyczaj oznacza to, że granica jest nieostra lub brakuje przejścia stanu.

Praktyczne następne kroki:

1. Najpierw naszkicuj granice i stany. Zdefiniuj mały zestaw stanów dla workflowu (np.: Created, PaymentPending, Paid, FulfillmentPending, Completed, Failed).

2. Dodaj idempotencję tam, gdzie najbardziej się liczy. Zacznij od najbardziej ryzykownych zapisów: create order, capture payment, issue refund. Przechowuj klucze idempotencji w PostgreSQL z unikalnym ograniczeniem, żeby duplikaty były odrzucane bezpiecznie.

3. Traktuj rekoncyliację jak normalną funkcję. Zaplanuj zadanie, które wyszukuje rekordy „pending za długo”, sprawdza zewnętrzne systemy i naprawia lokalny stan.

4. Iteruj bezpiecznie. Dostosuj przejścia i reguły ponawiania, a potem testuj, celowo ponawiając to samo żądanie i ponownie przetwarzając to samo zdarzenie.

Jeśli budujesz szybko na platformie sterowanej czatem jak Koder.ai (koder.ai), nadal warto wdrożyć te reguły w wygenerowanych serwisach od początku: szybkość pochodzi z automatyzacji, ale niezawodność pochodzi z jasnych granic, idempotentnych handlerów i rekoncyliacji.