Błąd integracji nie zawsze da się rozwiązać przez ponowienie próby. Jeśli brakuje danych, występuje rozbieżność biznesowa albo system docelowy wymaga podjęcia decyzji, ponowne wysłanie tego samego żądania może spowodować kolejne błędy, a nawet zduplikować skutki operacji. Obsługa wyjątków w integracjach PHP polega na wykrywaniu takich przypadków, zachowywaniu niezbędnych informacji oraz zapewnieniu kontrolowanej ścieżki ich analizy i rozwiązania.
Celem nie jest domyślne budowanie kolejnego backoffice’u. Chodzi o to, aby wyjątki były widoczne, zrozumiałe i przypisywalne, a każda ręczna czynność pozostawiała weryfikowalny zapis. Dobre rozwiązanie oddziela logikę poszczególnych integracji od wspólnego procesu weryfikacji, nie ukrywając przy tym różnic wpływających na bezpieczeństwo lub wynik biznesowy.
Kiedy przestać automatycznie ponawiać próby
Ponawianie prób sprawdza się w przypadku prawdopodobnie przejściowych awarii: rozłączenia, tymczasowego limitu żądań lub chwilowej niedostępności odpowiedzi. Warto ograniczyć je za pomocą jawnej polityki, na przykład maksymalnej liczby prób i stopniowo wydłużanych odstępów między nimi. Jeśli problem nie ustępuje, przepływ powinien przestać ponawiać próby i przejść do stanu, który można zbadać.
Odrzucenie z powodu nieprawidłowych danych, nieistniejącego odwołania lub niespełnionej reguły biznesowej zazwyczaj wymaga innego działania. Ponowienie próby bez zmiany warunków nie rozwiąże problemu. Interwencji może też wymagać operacja o niepewnym wyniku: na przykład gdy po wysłaniu żądania połączenie zostało przerwane i nie wiadomo, czy system zewnętrzny je przetworzył. W takim przypadku przed ponowieniem należy sprawdzić stan albo zastosować mechanizm zapobiegający duplikatom.
Dla każdej integracji określ, które błędy są przejściowe, które ostateczne, a które wymagają weryfikacji. Umieść tę klasyfikację przy kontrakcie integracji, zamiast rozpraszać ją w różnych warunkach w kontrolerach. Dzięki temu zmiana techniczna nie zmieni przypadkowo sposobu postępowania operacyjnego.
Zachowywanie kontekstu przydatnego w analizie
Nie należy zmuszać pracownika do odtwarzania transakcji przez osobne sprawdzanie logów aplikacji, baz danych i systemów zewnętrznych. Każdy wyjątek powinien zawierać informacje potrzebne do zrozumienia, co się stało, i podjęcia decyzji o dalszym działaniu, z zachowaniem zasad ochrony danych.
- Identyfikacja: identyfikator wyjątku, przepływu i powiązanej jednostki biznesowej.
- Źródło i cel: zaangażowana integracja, operacja i system zewnętrzny, bez zapisywania sekretów ani danych uwierzytelniających.
- Stan techniczny: data, liczba prób, wynik, kod odpowiedzi i znormalizowany opis błędu.
- Kontekst biznesowy: istotne pola i odwołania potrzebne do rozwiązania sprawy, z ograniczeniem lub redakcją danych wrażliwych.
- Korelacja: identyfikatory umożliwiające odnalezienie powiązanych logów w różnych usługach.
Zapisuj migawkę kontekstu wyjaśniającą błąd, a w razie potrzeby również odwołania do aktualnych danych. Jeśli rekordy zostaną później zmienione, analiza powinna pozwalać odróżnić dane pierwotnie wysłane od obecnych. Ustal limity dostępu i okresy przechowywania odpowiednie do wrażliwości informacji.
Jawne modelowanie stanów i przejść
Stany opisują sytuację operacyjną; nie są jedynie etykietami wizualnymi. Początkowy zestaw może obejmować oczekuje na weryfikację, w trakcie analizy, rozwiązany i odrzucony. Dodawaj stany pośrednie tylko wtedy, gdy zmieniają to, co system może zrobić lub czego oczekuje się od osoby odpowiedzialnej.
Określ, które przejścia są dozwolone. Na przykład oczekujący na weryfikację wyjątek można przypisać i przenieść do analizy; rozwiązany wyjątek powinien zachować wynik korekty oraz, jeśli ma to zastosowanie, identyfikator nowego wykonania. Odrzucenie nie może oznaczać usunięcia: wymaga podania przyczyny, a jego wpływ na przepływ musi być jasny. Nie zezwalaj na dowolne zmiany stanu z dowolnego ekranu lub procesu.
Jeśli poprawia to czytelność, oddziel stan weryfikacji od wyniku technicznego. Wyjątek może być rozwiązany operacyjnie, podczas gdy ponowione wykonanie nadal oczekuje na potwierdzenie. Osobne przedstawienie tych wymiarów pozwala uniknąć niejednoznacznych stanów i ułatwia ustalenie, czy pozostały jeszcze jakieś działania.
Przypisywanie odpowiedzialnych osób, terminów i eskalacji
Kolejka bez właściciela gromadzi nierozwiązane sprawy. Przypisuj je według zrozumiałych reguł, takich jak rodzaj operacji, zespół utrzymujący proces lub obszar biznesowy, który może poprawić dane. Umożliwiaj zmianę przypisania z podaniem przyczyny i zachowuj zarówno poprzednie, jak i nowe przypisanie.
Terminy powinny określać oczekiwania operacyjne, a nie stanowić automatycznej obietnicy rozwiązania. Ustal, jak długo sprawa może czekać na weryfikację i co dzieje się po przekroczeniu tego czasu: powiadomienie osoby odpowiedzialnej, eskalacja do zespołu lub przeniesienie do kolejki o wyższym priorytecie. Unikaj wpisywania konkretnych osób na stałe w każdej integracji; stosuj konfigurowalne reguły i rozwiązanie zastępcze na wypadek niedostępności osoby odpowiedzialnej.
Interfejs powinien szybko pokazywać, które sprawy wymagają uwagi, kto się nimi zajmuje i jak długo czekają. Jeśli znaczenie ma liczba spraw lub godziny obsługi, zdefiniuj osobne reguły według priorytetu i rodzaju wyjątku, zamiast stosować jeden termin dla wszystkich.
Rejestrowanie działań i bezpieczne ponawianie prób
Każda interwencja powinna tworzyć zdarzenie audytowe: kto podjął działanie, kiedy, co zrobił, z jakiego powodu oraz jaki był stan przed i po. Osobno rejestruj zmiany ręczne, automatyczne wykonania i odpowiedzi systemu zewnętrznego. Nie nadpisuj historii, aby wyświetlać wyłącznie bieżący stan.
Zanim udostępnisz opcję ponowienia operacji, ustal, czy jest ona idempotentna. Jeśli system docelowy na to pozwala, użyj stabilnego klucza idempotencji, aby ponowienie tej samej operacji nie powodowało drugiego efektu. Jeśli takiej gwarancji nie ma, najpierw sprawdź stan zdalny albo wprowadź etap uzgadniania; gdy wyniku nie da się zweryfikować, pokaż tę niepewność i wymagaj decyzji uprawnionej osoby.
Przed wykonaniem ponownie zweryfikuj dane i reguły biznesowe. Ręczne działanie nie może pomijać walidacji chroniących przepływ. Zapisuj powiązanie między pierwotnym wyjątkiem a nową próbą i jednoznacznie informuj, czy operacja została zaakceptowana, odrzucona, czy oczekuje na potwierdzenie. Opcja poprawienia danych powinna wskazywać, które pola zostaną zmienione oraz czy korekta dotyczy rekordu źródłowego, czy tylko wysyłanego żądania.
Mierzenie działania kolejki
Sama łączna liczba wyjątków nie wystarczy do zdiagnozowania procesu. Monitoruj czas do pierwszej weryfikacji i rozwiązania sprawy, wiek otwartych spraw, liczbę ponownie otwartych spraw, liczbę prób przypadających na wyjątek oraz odsetek spraw kończących się odrzuceniem. Dziel dane według integracji, rodzaju błędu i zespołu, nie zamieniając wskaźników w zachętę do zamykania spraw bez ich rozwiązania.
Wzrost liczby powtarzających się wyjątków może wskazywać na zmianę kontraktu API, niewystarczającą walidację lub błędne dane źródłowe. Wydłużenie czasu oczekiwania przy niezmienionej liczbie spraw może oznaczać niewystarczające zasoby lub nieskuteczne reguły przypisywania. Zestawiaj metryki z alertami o starzejącej się kolejce i analizuj próbki spraw, aby potwierdzić przyczynę.
Wybór między konsolą a backoffice’em
Ograniczony interfejs do obsługi spraw może wystarczyć, jeśli pracownicy muszą przeglądać kontekst, przypisywać sprawy, dodawać notatki, zmieniać stany i zlecać kontrolowane ponowienie próby. Powinien ułatwiać częste zadania, zapewniać odpowiednie uprawnienia i wyświetlać historię bez ujawniania zbędnych informacji.
Szerszy backoffice warto rozważyć, gdy praca obejmuje powiązane procesy, edycję jednostek biznesowych, zatwierdzenia, wyszukiwanie przekrojowe lub złożone zarządzanie uprawnieniami. Nie utożsamiaj kolejki operacyjnej z pełnym systemem administracyjnym: rozszerzaj zakres tylko wtedy, gdy istnieją rzeczywiste potrzeby, których ograniczony interfejs nie może bezpiecznie zaspokoić.
Lista kontrolna przed wdrożeniem obsługi wyjątków
- Klasyfikuj błędy jako przejściowe, ostateczne lub o niepewnym wyniku.
- Określ stany, przejścia, przyczyny zamknięcia i zasady ponownego otwierania.
- Zapisuj wystarczający kontekst, minimalizując i chroniąc dane wrażliwe.
- Wyznaczaj osoby odpowiedzialne, terminy i ścieżki eskalacji wraz z rozwiązaniem zastępczym.
- Rejestruj zmiany i łącz każdą interwencję z późniejszymi próbami.
- Waliduj dane przed ponowieniem i zabezpieczaj się przed powieleniem skutków.
- Mierz wiek spraw, czas obsługi i powtarzające się wzorce, a nie tylko liczbę spraw.
- Dobierz interfejs do wykonywanych zadań oraz zweryfikuj uprawnienia i okresy przechowywania.
Rzetelna obsługa wyjątków nie eliminuje wszystkich awarii. Jasno określa, co powinno się wydarzyć, gdy automatyzacja nie wystarcza, zapobiega ślepemu ponawianiu prób i pozwala każdej osobie działać w oparciu o kontekst, odpowiedzialność i identyfikowalność.
