Obsługa błędów w przepływie NextPDF Connect

W skrócie

Buduj odporne przepływy Connect. Sprawdzaj każdy wynik narzędzia, zamykaj nieudaną sesję i ponawiaj próbę z nowego stanu. Narzędzie zakończone niepowodzeniem zwraca ustrukturyzowany wynik błędu. Traktuj ten wynik jako normalną odpowiedź, a nie awarię transportu. PHP Standards Recommendation (PSR)-18 wprowadza to samo rozróżnienie: odpowiedź jest zwracana nawet wtedy, gdy status sygnalizuje błąd (PSR-18 §3).

Instalacja

composer require nextpdf/server

Skonfiguruj transport. Ten przepis wykorzystuje create_pdf, add_text oraz output_pdf. Wszystkie trzy narzędzia należą do edycji Core.

Przegląd koncepcyjny

Nieudane wywołanie narzędzia zwraca wynik błędu. Wynik zawiera flagę błędu, czytelny dla człowieka komunikat oraz kod, jeśli ma zastosowanie. Pomyślny wynik nie ma flagi błędu i zawiera standardowe dane wyjściowe narzędzia. W obu przypadkach transport wysłał żądanie i otrzymał odpowiedź (PSR-18 §p2).

Utrzymuj krótką pętlę obronną. Wyślij wywołanie, a następnie odczytaj wynik. Jeśli wynikiem jest błąd, zarejestruj go, sklasyfikuj, zastosuj strategię odzyskiwania i przestań używać nieaktualnego stanu. W przeciwnym razie wyodrębnij potrzebne pola i kontynuuj.

Powierzchnia API

Narzędzie	Rola	Poziom ryzyka
`create_pdf`	Otwiera sesję	Bezpieczne
`add_text`	Zapisuje tekst	Ostrożność
`output_pdf`	Renderuje i zwraca plik PDF	Wymagane zatwierdzenie / Przegląd (base64)

Katalog narzędzi jest źródłem prawdy. Dostępne narzędzia zależą od zainstalowanej edycji.

Przykład kodu — szybki start

Uruchom ścieżkę pozytywną (create_pdf → add_text → output_pdf) i sprawdź każdy wynik. Następnie celowo użyj ponownie unieważnionego document_id w add_text, aby wywołać błąd sesji. Przywróć działanie, tworząc nową sesję i odtwarzając zawartość.

Przykład kodu — produkcja

Klasyfikuj błędy według kategorii, a następnie reaguj odpowiednio:

Walidacja danych wejściowych — deterministyczna. Popraw argumenty, a następnie ponów to samo wywołanie. Przykłady: pusty tekst, nieprawidłowe wyrównanie, niedodatni rozmiar, nieznany rozmiar strony, nieznana rodzina czcionek.
Sesja — document_id już nie istnieje. Utwórz nową sesję, a następnie odtwórz całą zawartość.
System — ograniczenie zasobów serwera, takie jak limit sesji. Odczekaj, a następnie ponów próbę.
Zatwierdzenie — zapis output_pdf do pliku może zostać wstrzymany w oczekiwaniu na zatwierdzenie przez człowieka. To wstrzymanie przepływu pracy, a nie awaria. Przekaż wyzwanie i poczekaj, a następnie wywołaj ponownie z tokenem potwierdzenia.

Nigdy nie zakładaj powodzenia. Nigdy nie używaj ponownie document_id po błędzie sesji. Nigdy nie wysyłaj output_pdf, dopóki każdy krok dotyczący zawartości nie zakończy się powodzeniem.

Przypadki brzegowe i pułapki

Zatwierdzenie nie jest błędem. Wyzwanie z udziałem człowieka (HITL) oznacza wstrzymanie. Nie ponawiaj prób w ciasnej pętli. Przekaż je człowiekowi.
Ponowne uruchomienie serwera. Wszystkie sesje w pamięci są czyszczone, a każdy wcześniejszy document_id staje się nieprawidłowy.
Częściowy przepływ pracy. Jeśli add_text zawiedzie w środku dokumentu, sesja może być niespójna. Bezpiecznym sposobem odzyskania jest utworzenie nowej sesji, a nie częściowa naprawa.

Wydajność

Pomijalna. Ten przepis dotyczy przepływu sterowania, a nie renderowania. Profil dla każdego wytworzonego wyniku to structural.

Uwagi dotyczące bezpieczeństwa

Komunikaty o błędach są przeznaczone dla agenta wywołującego i operatora. Nie przekazuj niezaufanym użytkownikom końcowym surowego tekstu błędu serwera w dosłownym brzmieniu. Zamiast tego pokaż sklasyfikowany, oczyszczony komunikat.

Zgodność

Twierdzenie	Specyfikacja	Klauzula	reference_id
Transport zwraca odpowiedź niezależnie od wyniku.	PSR-18	§p2
Odpowiedź jest zwracana nawet przy statusie błędu.	PSR-18	§3

Kontekst komercyjny

Nie dotyczy — wszystkie narzędzia należą do edycji Core.

Dostępność transportów

Transport	Dostępny	Uwagi
MCP (stdio)	Tak	Błędy przychodzą jako wynik narzędzia z flagą błędu.
REST	Tak	Status inny niż 2xx zawiera to samo sklasyfikowane ciało błędu.
gRPC	Tak	Kod statusu wraz z komunikatem o wyniku błędu.

W każdym transporcie analizuj błąd na poziomie narzędzia jako normalną odpowiedź, a nie przerwane wywołanie (PSR-18 §3).

Poziom ryzyka HITL

create_pdf jest oznaczone jako Safe, add_text jako Caution, a output_pdf jako Approval Required, obniżone do Review w trybie base64. Oczekujący zapis pliku pojawia się jako wyzwanie zatwierdzenia. Pętla obsługi błędów musi traktować je jako wstrzymanie, a nie awarię (poziomy ryzyka HITL).

Koperta JSON bramki potwierdzenia

Oczekujące zatwierdzenie zwraca:

{ "allowed": false, "challenge": "<human-readable challenge text>", "token": "confirm_<single-use-hex>" }

Wywołaj ponownie to samo narzędzie z _confirmation_token ustawionym na ten token. Narzędzie zwraca { "allowed": true }. Pełny przebieg opisano w output-approval.