- sara.next
- Technologia
- Obsługa błędów i wyjątków
Technologia · Dla deweloperów
Obsługa błędów i wyjątków
Najważniejszy test integracji IGA zaczyna się wtedy, gdy zatwierdzona zmiana nie może zostać wykonana — albo nie wiadomo, czy została wykonana.
- Implemented / Not implemented
- timeout
- idempotencja
Kontekst
Różnica między błędem technicznym a błędem procesu
Nie wszystkie niepowodzenia są takie same. Zgłoszenie może zostać odrzucone na etapie autoryzacji, skrypt może nie skompilować się, REST API może odmówić dostępu, a system docelowy może wykonać zmianę, lecz nie potwierdzić jej przed timeoutem. Każdy z tych przypadków wymaga innej reakcji, ponieważ inne jest ryzyko pozostawienia nieprawidłowych uprawnień.
Mechanizm autoimplementacji sara.next posługuje się stanami „Implemented” i „Not implemented”, z komunikatem o błędzie. Dokumentacja omawia m.in. niepowodzenie kompilacji skryptu Groovy, wyjątki przy nieobecnych zmiennych oldUser lub request.oldAtar, błędne wartości identyfikatorów, różnice w schemacie SQL, błędy uwierzytelnienia REST oraz opóźnienie po stronie API.
Macierz obsługi
Praktyczne scenariusze
| Problem | Potencjalna przyczyna | Zalecane działanie |
|---|---|---|
| Błąd kompilacji Groovy | Składnia, brak zmiennej, błędny typ danych | Poprawka w środowisku testowym, testy jednostkowe skryptu, ponowny odbiór |
NullPointerException | Użycie oldUser w niewłaściwej operacji lub brak oldAtar | Sprawdzenie kontraktu zmiennych i null-safe navigation |
| HTTP 401/403 | Niepoprawny lub niewystarczający sekret albo zakres konta | Kontrola konfiguracji połączenia i uprawnień, bez logowania sekretów |
| HTTP 429/503 | Limit API albo przejściowa niedostępność | Kontrolowana obsługa rate limit, ustalenie sposobu retry |
| Timeout po wysłaniu | Niepewność, czy żądanie wykonało się | Najpierw odczyt stanu docelowego, dopiero potem decyzja o ponowieniu |
| SQL zwrócił błąd | Uprawnienia, constraint, niepoprawne dane, blokada | Analiza transakcji i danych, poprawka bez nadawania nadmiarowych przywilejów |
| Weryfikacja nie przeszła | Niespójny stan, błąd zapytania lub opóźnienie propagacji | Porównanie stanu faktycznego z oczekiwanym, identyfikacja punktu niezgodności |
| Część zmian w zewnętrznych systemach się powiodła | Brak transakcji rozproszonej | Procedura kompensacyjna, ręczna interwencja, raport incydentu lub wyjątku |
Diagnostyka
Typowe błędy skryptów i ich przyczyny
Komunikaty, które najczęściej pojawiają się przy pierwszej konfiguracji autoimplementacji.
| Objaw | Przyczyna | Co zrobić |
|---|---|---|
Groovy script compilation failed: ... | Błąd składni skryptu: niezamknięty napis, brakujący nawias albo niepoprawna składnia Groovy. | Komunikat błędu zawiera numer wiersza — od niego zacznij. |
NullPointerException przy oldUser | oldUser jest dostępny tylko dla wniosków Delete i Replace. Odwołanie do niego w skrypcie Create kończy się wyjątkiem. | Jeżeli skrypt jest współdzielony, używaj bezpiecznej nawigacji: oldUser?.samAccountName. |
NullPointerException przy request.oldAtar | request.oldAtar jest ustawiane tylko dla wniosków Modify i Delete (przechowuje poprzedni rekord dostępu). | Zawsze używaj bezpiecznej nawigacji: request.oldAtar?.dimensionValues. |
Weryfikacja SQL nieoczekiwanie zwraca false | Zapytanie SELECT nie zwróciło wierszy: login nie odpowiada zapisanej wartości (wielkość liter, prefiks domeny), tabela lub widok są inne niż zakładano albo skrypt implementacyjny nie wykonał zmiany. | Sprawdź komentarz przy pozycji w kolejce — zawiera szczegóły. |
Weryfikacja REST nieoczekiwanie zwraca false | Żądanie GET zwróciło status inny niż 2xx: błędna ścieżka lub zasób nie powstał, nieudane uwierzytelnienie albo opóźnienie po stronie API. | Sprawdź poświadczenia połączenia REST i rozważ, czy weryfikacja musi następować natychmiast. |
Odzyskiwanie
Cztery zasady odzyskiwania
Nie ponawiaj „w ciemno”
Po timeoutach sprawdź stan, by nie tworzyć podwójnych kont albo konfliktujących przypisań.
Oddziel retry od decyzji biznesowej
Ponowne wykonanie zatwierdzonej operacji może być technicznie uzasadnione, lecz zmiana zakresu uprawnienia wymaga nowej decyzji.
Używaj idempotencji tam, gdzie to możliwe
grantpowinien wykrywać istniejące przypisanie, arevokebrak przypisania; ostateczne zachowanie zależy od docelowego API lub SQL.Dokumentuj rozbieżności
Przechowuj identyfikator zgłoszenia, aplikację, typ operacji, informację o błędzie, wynik kontroli stanu oraz decyzję o sposobie przywrócenia spójności.
Transakcje
Zależność od modelu transakcyjnego
W SQL dokumentacja wskazuje wykonanie listy instrukcji w jednej transakcji. Nie należy przenosić tego wniosku na kilka wywołań HTTP lub kilka systemów docelowych. W REST operacja POST zakończona timeoutem nie daje podstaw do uznania, że nie zadziałała. Prawidłowy projekt wykorzystuje zapytanie kontrolne do odczytania rzeczywistego przypisania.
Logi
Obsługa błędów bez ujawniania danych wrażliwych
Logi powinny zawierać identyfikator korelacyjny, typ operacji, status i kod błędu.
UwagaLogi nie powinny zawierać haseł, tokenów Bearer, API key, pełnych danych osobowych ani treści zapytań z sekretami.
W środowiskach regulowanych należy zdefiniować politykę retencji i uprawnienia dostępu do logów. Implementacja tych kontroli powinna zostać zweryfikowana w konkretnej konfiguracji.
Opinia eksperta wdrożeniowego
Najbardziej ryzykowny status: „nie wiem”
W procesie nadawania uprawnień najbardziej ryzykowny status brzmi: „nie wiem, czy zmiana się wykonała”. Właśnie dla takich przypadków projektowałbym integrację.
Monitoring błędów ma sens dopiero wtedy, gdy wiadomo, kto odpowiada za decyzję, jak sprawdzić faktyczny stan i jak zamknąć wyjątek bez utraty śladu audytowego.
Zakres
Co potwierdza dokumentacja, a co wymaga projektu
Potwierdzone
- podstawowe statusy rezultatu autoimplementacji,
- możliwość weryfikacji,
- przykłady błędów Groovy, SQL i REST.
Wzorce rekomendowane, nie gwarancje platformy
- polityka retry i backoff,
- dead-letter queue,
- circuit breaker,
- centralne alertowanie,
- rozproszona kompensacja,
- automatyczna rekonsyliacja.
Zweryfikuj z nami scenariusze awaryjne integracji
Najlepiej jeszcze przed uruchomieniem produkcyjnym.