Wzorzec circuit breaker dla zewnętrznych API w wizualnych przepływach pracy

Dlaczego awarie zewnętrznych API psują więcej niż jedną funkcję

Pojedyncze zewnętrzne API często znajduje się w środku codziennych procesów: przyjmowanie płatności, sprawdzanie adresów, synchronizacja stanów magazynowych, wysyłka wiadomości, weryfikacja tożsamości. Gdy ten dostawca ma problemy, rzadko psuje tylko jeden przycisk. Może zatrzymać całe przepływy, które czekają na jego odpowiedź.

Dlatego circuit breaker ma znaczenie. To nie teoria — to praktyczny sposób, by kluczowe operacje działały dalej, nawet gdy integracja jest niezdrowa.

Wolne i niedostępne szkodzi inaczej.

Gdy API jest wolne, przepływ nadal próbuje odnieść sukces, ale każdy krok czeka. Użytkownicy widzą kręcące się ekrany, support dostaje zgłoszenia „to się zacięło”, a zadania w tle się kumulują. Wolne jest podstępne, bo może wyglądać jak awaria twojego systemu.

Gdy API jest niedostępne, pojawiają się timeouty lub twarde błędy. To jest czytelniejsze, ale często groźniejsze, bo workflowy mają tendencję do retry. Gdy wiele żądań próbuje ponownie naraz, tworzysz burzę ruchu, która utrudnia odzyskiwanie i może obciążyć własny system.

Typowe objawy pojawiają się szybko: timeouty, kolejki rosnące w nieskończoność, częściowe aktualizacje i dużo ręcznych porządków.

Prawdziwe szkody to efekt łańcuchowy. Jeśli dostawca taryf wysyłkowych jest wolny, składanie zamówienia zwalnia, bo workflow odmawia potwierdzenia bez wyceny. Jeśli płatności są niedostępne, support może nie móc wystawić zwrotu, mimo że wszystko inne działa.

Nie da się udawać, że awarie nie istnieją. Celem jest zaprojektować przepływy z jasnymi ścieżkami awaryjnymi, tymczasowymi zasadami blokowania i alertowaniem, żeby firma mogła przyjmować zamówienia, obsługiwać klientów i rejestrować pracę, podczas gdy integracja się regeneruje.

Circuit breaker prostymi słowami

Circuit breaker to wyłącznik bezpieczeństwa dla wywołań API. Gdy zewnętrzny serwis zaczyna zawodzić, breaker zatrzymuje twój workflow przed długimi, powtarzalnymi uderzeniami. Zamiast jednego problemu zmieniać w spowolnione ekrany, timeouty i zablokowane zadania, kontrolujesz zasięg awarii.

Circuit breaker ma trzy proste wyniki:

• Zezwól na wywołanie, gdy dostawca wygląda na zdrowego.
• Zablokuj wywołanie, gdy awarii jest dużo, i od razu przejdź do fallbacku.
• Spróbuj ograniczonego wywołania testowego po krótkiej przerwie, by sprawdzić czy dostawca wrócił.

Jeśli wolisz etykiety, to „closed”, „open” i „half-open”. Nazwy nie są najważniejsze — przewidywalność jest. Gdy dostawca jest chory, twój workflow powinien zachowywać się tak samo za każdym razem.

To nie ukrywa błędów. Nadal rejestrujesz awarie, pokazujesz jasny status użytkownikom lub operacjom i alarmujesz właściwe osoby. Wybierasz szybkie zakończenie, przekierowanie pracy na bezpieczniejszą alternatywę lub krótką pauzę przed ponownym testem.

Wybierz, które wywołania API nigdy nie mogą zatrzymać biznesu

Circuit breakery działają najlepiej, gdy jesteś selektywny. Nie każde wywołanie dostawcy wymaga specjalnej ochrony. Zacznij od kroków, które, jeśli zostaną zablokowane, zatrzymają pieniądze, zamówienia lub dostęp klienta.

Praktyczna metoda to śledzenie jednego żądania użytkownika od początku do końca. Gdzie timeout zmusiłby użytkownika do porzucenia zadania albo stworzyłby bałagan do ręcznego posprzątania?

Typowe wywołania, które "nie mogą zablokować kluczowej pracy", to płatności, wysyłka i fulfillment, logowanie/SSO/MFA, OTP i wiadomości potwierdzające oraz kontrole zgodności związane z zatwierdzeniem.

Oddziel też kroki widoczne dla użytkownika od zadań w tle. Jeśli ktoś czeka na ekranie checkout, potrzebujesz szybkiej decyzji: powiodło się, fallback, czy zatrzymać z jasnym komunikatem. Dla prac w tle, jak synchronizacja numerów śledzenia, wolniejsze retry są w porządku, o ile nigdy nie blokują głównego przepływu.

Zacznij mało, by uniknąć rozrostu zakresu. Chroń najpierw 1–3 workflowy, potem rozszerzaj.

Zdefiniuj, co znaczy „bezpieczny fallback” zanim cokolwiek zbudujesz. Dobre fallbacky są konkretne i łatwe do przetestowania:

• Płatności: zapisz zamówienie jako „płatność oczekująca”, żeby koszyk nie zaginął.
• Wysyłka: użyj zbuforowanej stawki, stałej opłaty lub potwierdź zamówienie i opóźnij zakup etykiety.
• Tożsamość: pozwól logowanie hasłem, gdy SSO jest niedostępne, lub przełącz na weryfikację e-mail.
• Wiadomości: kolejkować SMS na później i tam, gdzie możliwe, zapewnić alternatywną ścieżkę.

W Business Process Editor w AppMaster często przechodzi to w czystą gałąź: główna operacja trwa dalej, a krok zależny od dostawcy idzie kontrolowaną alternatywą.

Stany, progi i timery, które możesz wyjaśnić

Circuit breaker to wyłącznik bezpieczeństwa. Większość czasu przepuszcza wywołania. Gdy dostawca zaczyna zawodzić, przełącza się, by chronić workflow przed marnowanym czasem i narastającymi błędami.

Trzy stany

Closed to normalny stan. Wywołujesz API i kontynuujesz.

Gdy awarie przekroczą linię, breaker przechodzi w Open. Przestajesz wywoływać dostawcę przez krótki okres i od razu kierujesz do fallbacku (wartość z pamięci, kolejka, alternatywny flow).

Po okresie chłodzenia breaker przechodzi w Half-open. Pozwalasz na niewielką liczbę testowych wywołań. Jeśli powiedzie się, wracasz do Closed. Jeśli zawiedzie, wracasz do Open.

Co mierzyć

Używaj sygnałów, które odpowiadają temu, jak dostawca zawodzi:

• Timeouty
• HTTP 5xx
• Rosnąca latencja (zbyt wolno, by było użyteczne)
• Błędy połączeń/DNS
• 429 rate limit

W narzędziu wizualnym te sygnały zwykle mapują się na proste sprawdzenia: kod statusu, upłynięty czas i konkretne komunikaty błędu.

Progi startowe i dwa kluczowe timery

Zacznij od liczb prostych do wytłumaczenia, potem dopracuj na podstawie ruchu. Przykłady:

• Otwórz breaker, jeśli 5–10 wywołań zawiedzie w ciągu 30–60 sekund.
• Albo otwórz, jeśli 20%–40% wywołań zawiedzie w ruchomym oknie.
• Traktuj latencję jako błąd, gdy przekracza to, co proces toleruje (często 2–5 sekund).

Następnie ustaw dwa timery:

• Czas chłodzenia (stan Open): często 30 sekund do 5 minut.
• Okno testowe w Half-open: pozwól na 1–5 testowych wywołań lub krótkie okno 10–30 sekund.

Celem jest proste: szybko przerwać, gdy dostawca jest niezdrowy, i automatycznie wrócić, gdy jest z powrotem.

Krok po kroku: zbuduj circuit breaker w wizualnym przepływie

Najważniejszy wybór projektowy to zrobić decyzję „czy dzwonimy teraz do dostawcy?” w jednym miejscu, a nie rozsiane po każdym workflow.

1) Umieść wywołanie dostawcy za jednym wielokrotnego użytku blokiem

Utwórz podproces (blok wielokrotnego użytku), którego każdy workflow będzie używać przy potrzebie wywołania dostawcy. W AppMaster naturalnie mapuje się to na Business Process, który możesz wywołać z endpointów lub automatyzacji. Trzymaj go wąsko: wejścia, żądanie do dostawcy i wyraźny wynik sukces/porażka.

2) Śledź awarie w czasie, nie tylko liczniki

Zapisuj każde zdarzenie z timestampem. Przechowuj np. ostatni sukces, ostatnią porażkę, liczbę porażek w oknie, bieżący stan i deadline chłodzenia.

Persistuj te pola w tabeli, żeby breaker przetrwał restarty i był spójny między instancjami. PostgreSQL przez Data Designer dobrze się do tego nadaje.

3) Zdefiniuj zmiany stanu, których będziesz przestrzegać za każdym razem

Utrzymuj proste reguły. Przykład: jeśli 5 porażek wystąpi w ciągu 2 minut, przełącz na Open. W stanie Open pomijaj wywołanie dostawcy aż do upływu cooldownu. Po cooldownie idź do Half-open i pozwól na jedną kontrolowaną próbę. Jeśli się uda, zamknij breaker. Jeśli nie, otwórz go ponownie.

4) Rozgałęzienie workflow: ścieżka dostawcy vs fallback

Przed wywołaniem dostawcy sprawdź zapisany stan:

• Closed: zadzwoń do dostawcy, potem zaktualizuj sukces lub porażkę.
• Open: pomiń wywołanie i wykonaj fallback.
• Half-open: pozwól na ograniczoną próbę, potem zdecyduj czy zamknąć czy ponownie otworzyć.

Przykład: jeśli API etykiet wysyłkowych jest niedostępne, fallback może stworzyć zamówienie ze statusem „Label pending” i kolejkować zadanie retry, zamiast blokować checkout lub pracę magazynu.

5) Uczyń to współdzielonym między workflowami

Jeśli masz wiele workflowów i serwerów, muszą czytać i zapisywać ten sam stan breakera. W przeciwnym razie jedna instancja może dalej katować dostawcę, podczas gdy inna już postanowiła się zatrzymać.

Ścieżki fallback, które utrzymują pracę

Circuit breaker pomaga tylko wtedy, gdy zdecydujesz, co się stanie, gdy wywołanie jest zablokowane. Dobry fallback pozwala użytkownikowi działać, chroni dane i sprawia, że późniejsze porządki są przewidywalne.

Wybierz fallback pasujący do zadania. Jeśli dostawca stawek wysyłkowych padł, możesz nie potrzebować dokładnej ceny, by zaakceptować zamówienie. W wizualnym workflowie skieruj krok API do gałęzi fallback, która nadal daje użyteczny rezultat.

W praktyce fallbacky zwykle wyglądają tak:

• Użyj ostatniej znanej wartości z pamięci podręcznej (z jasnym oknem świeżości).
• Użyj bezpiecznego szacunku/stałej stawki, wyraźnie oznaczonej.
• Skieruj do ręcznego przeglądu.
• Kolejkowanie pracy do ponowienia później (asynchroniczne zadanie).

Doświadczenie użytkownika jest równie ważne co logika. Nie pokazuj mgławicowego błędu. Powiedz, co się stało i co użytkownik może zrobić dalej: „Nie udało nam się potwierdzić stawki teraz. Możesz złożyć zamówienie z szacunkowym kosztem wysyłki lub zapisać je do przeglądu.”

Planuj też krótkie vs długie przerwy. Krótka awaria (minuty) zwykle oznacza „idź dalej, retry w tle”. Dłuższa awaria (godziny) może wymagać ostrzejszych działań, jak ręczna weryfikacja lub zatwierdzenia.

Na koniec śledź każdy fallback, by rekonsyliacja była prosta. Przynajmniej rejestruj typ fallbacku, oryginalne szczegóły żądania, co zwrócono użytkownikowi (i czy to był szacunek) oraz status do dalszego działania.

Tymczasowe reguły blokowania i mądrzejsze retry

Niekontrolowane retry zamieniają małe przycięcia dostawcy w prawdziwe awarie. Gdy wiele workflowów retryuje jednocześnie, tworzy się skok (thundering herd). Dostawca zwalnia, twoje kolejki rosną, a limity rate są spalane.

Retryy powinny być przewidywalne i ograniczone oraz respektować stan breakera. Praktyczna polityka:

• Trzymaj maksymalną liczbę retry niską (zwykle 2–3).
• Używaj wykładniczego backoffu (np. 2s, 8s, 30s).
• Dodaj jitter, by retry nie synchronizowały się.
• Ogranicz całkowity czas retry (np. 60–90 sekund).
• Jeśli breaker jest Open, nie retryuj — idź od razu do fallbacku.

Tymczasowe blokowanie jest powiązane, ale inne. Dotyczy przypadków, gdy odpowiedź mówi „to teraz nie zadziała”. Typowe reguły:

• 429 rate limit: zablokuj na okres Retry-After (lub bezpieczne stałe okno).
• 401/403 błąd autoryzacji: zablokuj do odświeżenia poświadczeń, potem wykonaj jedną próbę testową.
• Stałe 5xx: zablokuj krótko, potem pozwól na mały test.

Podczas blokady zdecyduj, co dzieje się z pracą już w ruchu: kolejkować, przekierować lub zdegenerować (np. zaakceptować zamówienie, ale opóźnić „wysyłkę SMS”).

Alertowanie, które mówi co robić

Circuit breaker pomaga tylko wtedy, gdy ludzie szybko o tym usłyszą i będą wiedzieć, co robić. Cel to nie hałas, lecz jedna jasna wiadomość, gdy zachowanie się zmieni: wywołania są blokowane, fallbacki są aktywne albo breaker pozostaje otwarty dłużej niż oczekiwano.

Dobre domyślne wyzwalacze:

• Alert przy otwarciu breakera.
• Alert gdy pozostaje otwarty dłużej niż limit.
• Alert przy gwałtownym wzroście błędów jeszcze przed otwarciem.

Zrób alerty wykonalnymi. Dołącz dostawcę i endpoint, bieżący stan i kiedy się zmienił, co użytkownicy odczują, co workflow robi teraz (blokuje, retryuje, fallback), i jedną sugerowaną następną akcję.

Kieruj alerty według ważności. Nieistotne API wzbogacające może iść na e-mail. Płatności, logowanie czy składanie zamówień zwykle zasługują na paging. W AppMaster to mapuje się czysto na gałęzie wysyłające e-mail, Telegram lub SMS według flagi ważności.

Śledź mały zestaw metryk, by widzieć, czy się odzyskujesz: zablokowane wywołania i użycie fallbacków per dostawca często wystarczają.

Przykład scenariusza: awaria dostawcy bez zatrzymywania zamówień

Częsty problem: dostawca stawek wysyłkowych pada w momencie, gdy klienci finalizują zakup. Jeśli workflow wymaga żywych stawek podczas tworzenia zamówienia, jedna awaria może zatrzymać całe zamówienia.

W normalny dzień zamówienie jest tworzone, potem workflow żąda żywych stawek, i zamówienie jest zapisane z wybraną ceną.

Gdy dostawca zaczyna zawodzić, połączenia timeoutują lub zwracają 5xx. Gdy osiągniesz próg (np. 5 błędów w 2 minuty), breaker się otwiera.

W stanie Open workflow przestaje dzwonić do dostawcy na krótki okres (np. 10 minut). To zapobiega temu, by zawodny dostawca zahamował checkout dla wszystkich.

Zamiast blokować checkout, fallback może:

• Zastosować opłatę ryczałtową (lub bezpieczny szacunek).
• Stworzyć zamówienie mimo wszystko.
• Oznaczyć je jako „Shipping rate pending” do późniejszej rekalkulacji.
• Zapisać szczegóły błędu dostawcy do dalszego śledzenia.

W AppMaster to jasna gałąź w Business Process Editor, wsparta polami w Data Designer jak shipping_rate_status i shipping_rate_source.

Szybkie kontrole przed wdrożeniem

Circuit breaker powinien zachowywać się tak samo pod obciążeniem jak w demie. Przed wydaniem sprawdź podstawy:

• Progi i cooldowny są udokumentowane i łatwe do zmiany.
• Stan Open blokuje wywołania natychmiast (bez czekania na timeouty dostawcy).
• Zachowanie fallbacku jest bezpieczne dla pieniędzy i obietnic wobec klienta.
• Probowanie w Half-open jest ograniczone do kilku testowych wywołań.
• Logi ułatwiają udzielenie odpowiedzi na pytania o timing i wpływ.

Poświęć dodatkowy czas na bezpieczeństwo fallbacku. Fallback „utrzymujący pracę” może również tworzyć ryzyko finansowe. Jeśli dostawca płatności padł, oznaczanie zamówień jako opłaconych jest niebezpieczne. Bezpieczniejsze jest „płatność oczekująca” z jasnym komunikatem do klienta.

Testuj odzyskiwanie celowo. Wymuś awarie, obserwuj otwarcie breakera, przejdź przez cooldown i potwierdź, że Half-open wysyła tylko małą próbę. Jeśli się uda, powinien szybko zamknąć. Jeśli zawiedzie, powinien ponownie otworzyć bez zalewania dostawcy.

Twoje logi powinny odpowiedzieć w mniej niż minutę: kogo to dotknęło, kiedy się zaczęło, który krok workflow uruchomił breaker i jaki fallback został użyty.

Następne kroki: zaimplementuj wzorzec w AppMaster

Wybierz jedną integrację, która może szkodzić codziennej działalności, jeśli zawiedzie (płatności, etykiety wysyłkowe, SMS, synchronizacja CRM). Zbuduj breaker end-to-end dla tego pojedynczego wywołania najpierw. Gdy zespół zaufa zachowaniu, powiel ten szablon dla kolejnego dostawcy.

W AppMaster modeluj stan breakera w PostgreSQL przy użyciu Data Designer. Trzymaj to prosto: rekord na dostawcę (lub endpoint) z polami jak state, failure_count, last_failure_at, open_until i krótkim last_error.

Następnie zaimplementuj logikę w Business Process Editor z czytelnymi gałęziami. Jasność bije spryt.

Praktyczna kolejność budowy:

1. Sprawdź stan breakera i zablokuj wywołania, gdy open_until jest w przyszłości.
2. Zadzwoń do API dostawcy i złap zarówno wyjścia sukcesu, jak i błędu.
3. Przy sukcesie zresetuj liczniki i zamknij breaker.
4. Przy porażce zwiększ licznik i otwórz breaker, gdy progi zostaną spełnione.
5. Skieruj przepływy widoczne dla użytkownika do fallbacku (kolejkuj pracę, użyj zbuforowanych danych lub pozwól na ręczne przetwarzanie).

Udokumentuj decyzję fallbacku prostym językiem, aby support i ops wiedzieli, co widzi użytkownik.

Gdy breaker się otworzy, powiadom właściciela używając modułów messaging w AppMaster (e-mail, SMS, Telegram). Dołącz to, co ważne: dostawca, endpoint, stan i pierwsza zalecana akcja.

Jeśli budujesz te workflowy w AppMaster, appmaster.io to praktyczne miejsce na start, ponieważ ten sam wizualny Business Process może zasilać endpointy, zadania w tle i alertowanie z jednym współdzielonym stanem breakera.