NextPDF Connect iş akışında hataları işleme

Bir bakışta

Dayanıklı Connect iş akışları oluşturun. Her araç sonucunu doğrulayın, başarısız oturumu kapatın ve temiz bir durumdan yeniden deneyin. Başarısız bir araç, yapılandırılmış bir hata sonucu döndürür. Bu sonucu taşıma katmanı arızası değil, normal bir yanıt olarak ele alın. PHP Standards Recommendation (PSR)-18 aynı ayrımı yapar: durum bir hataya işaret etse bile yine de bir yanıt döndürülür (PSR-18 §3).

Kurulum

composer require nextpdf/server

Bir taşıma katmanı bağlayın. Bu tarifte create_pdf, add_text ve output_pdf araçları kullanılır. Üç aracın tamamı Core kapsamındadır.

Kavramsal genel bakış

Başarısız bir araç çağrısı hata sonucu döndürür. Sonuçta bir hata bayrağı, insan tarafından okunabilir bir ileti ve uygun olduğunda bir kod bulunur. Başarılı bir sonuçta hata bayrağı bulunmaz; sonuç aracın normal çıktısını taşır. Her iki durumda da taşıma katmanı isteği göndermiş ve yanıtı almıştır (PSR-18 §p2).

Savunma döngüsünü kısa tutun. Çağrıyı gönderin, ardından sonucu okuyun. Sonuç bir hataysa günlüğe kaydedin, sınıflandırın, kurtarma stratejisini uygulayın ve eski durumu kullanmayı bırakın. Aksi hâlde, ihtiyaç duyduğunuz alanları ayıklayın ve devam edin.

API yüzeyi

Araç	Rol	Risk düzeyi
`create_pdf`	Oturumu açar	Güvenli
`add_text`	Metin yazar	Dikkat
`output_pdf`	PDF’yi oluşturur ve döndürür	Onay Gerekli / İnceleme (base64)

Geçerli bilgi kaynağı, Araç kataloğu sayfasıdır. Araçların kullanılabilirliği, kurulu sürüm düzeyine bağlıdır.

Kod örneği — hızlı başlangıç

Sorunsuz akışı çalıştırın (create_pdf → add_text → output_pdf) ve her sonucu denetleyin. Ardından, bir oturum hatasını tetiklemek için yok edilmiş bir document_id değerini add_text çağrısında bilerek yeniden kullanın. Yeni bir oturum oluşturup içeriği yeniden uygulayarak bu durumdan kurtulun.

Kod örneği — üretim

Hataları kategoriye göre sınıflandırın ve buna göre yanıt verin:

Girdi doğrulaması — belirlenimcidir. Bağımsız değişkenleri düzeltin, ardından aynı çağrıyı yeniden deneyin. Örnekler: boş metin, geçersiz hizalama, pozitif olmayan boyut, bilinmeyen sayfa boyutu, bilinmeyen yazı tipi ailesi.
Oturum — document_id artık mevcut değildir. Yeni bir oturum oluşturun, ardından tüm içeriği yeniden uygulayın.
Sistem — oturum sınırı gibi bir sunucu kaynağı kısıtlamasıdır. Geri çekilme uygulayın, ardından yeniden deneyin.
Onay — bir dosyaya yönelik output_pdf işlemi, insan onayı için duraklayabilir. Bu bir arıza değil, iş akışı duraklamasıdır. Sınamayı iletin ve bekleyin, ardından onay belirteciyle yeniden çağırın.

Başarıyı asla varsaymayın. Bir oturum hatasından sonra bir document_id değerini asla yeniden kullanmayın. Her içerik adımı başarılı olana kadar output_pdf çağrısını asla göndermeyin.

Uç durumlar ve dikkat edilecek noktalar

Onay bir hata değildir. İnsan-döngüde (HITL) sınaması bir duraklamadır. Sıkı bir döngü içinde yeniden denemeyin. Durumu kullanıcıya iletin.
Sunucu yeniden başlatması. Bellek içindeki tüm oturumlar temizlenir ve önceki her document_id geçersiz hâle gelir.
Kısmi iş akışı. add_text belgenin ortasında başarısız olursa oturum tutarsız olabilir. Güvenli kurtarma yöntemi kısmi onarım değil, temiz bir oturumdur.

Performans

Etkisi ihmal edilebilir düzeydedir. Bu tarif, işlemeyi değil, denetim akışını kapsar. Üretilen her çıktı için profil structural biçimindedir.

Güvenlik notları

Hata iletileri, çağrıyı yapan araç ve operatöre yöneliktir. Ham sunucu hata metnini, güvenilmeyen son kullanıcılara birebir aktarmayın. Bunun yerine, sınıflandırılmış ve arındırılmış bir ileti gösterin.

Uygunluk

Beyan	Belirtim	Madde	reference_id
Taşıma katmanı, sonuçtan bağımsız olarak bir yanıt döndürür.	PSR-18	§p2
Bir hata durumunda bile yine de bir yanıt döndürülür.	PSR-18	§3

Ticari bağlam

Uygulanamaz — araçların tamamı Core kapsamındadır.

Taşıma katmanı kullanılabilirliği

Taşıma katmanı	Kullanılabilir	Notlar
MCP (stdio)	Evet	Hatalar, hata bayrağı taşıyan bir araç sonucu olarak gelir.
REST	Evet	2xx olmayan bir durum kodu, aynı sınıflandırılmış hata gövdesini taşır.
gRPC	Evet	Durum kodu ve hata sonucu iletisiyle gelir.

Her taşıma katmanında, araç düzeyindeki hatayı düşmüş bir çağrı değil, normal bir yanıt olarak değerlendirin (PSR-18 §3).

HITL risk düzeyi

create_pdf Güvenli, add_text Dikkat, output_pdf ise Onay Gerekli düzeyindedir; base64 kipinde İnceleme düzeyine iner. Bekleyen bir dosya yazma işlemi, onay sınaması olarak görünür. Hata işleme döngüsü bunu bir arıza değil, bir duraklama olarak ele almalıdır (HITL risk düzeyleri).

Onay geçidi JSON zarfı

Bekleyen bir onay şunu döndürür:

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

Aynı aracı _confirmation_token bu belirtece ayarlanmış olarak yeniden çağırın. Bu, { "allowed": true } döndürür. Akışın tamamı için bkz. output-approval.