Xử lý lỗi trong quy trình NextPDF Connect

Tổng quan nhanh

Xây dựng các quy trình làm việc Connect có khả năng phục hồi tốt. Xác thực mọi kết quả công cụ, đóng phiên đã lỗi và thử lại từ trạng thái mới. Một công cụ thất bại sẽ trả về kết quả lỗi có cấu trúc. Hãy xem kết quả đó là một phản hồi bình thường, không phải lỗi transport. PHP Standards Recommendation (PSR)-18 cũng phân biệt tương tự: phản hồi vẫn được trả về ngay cả khi trạng thái cho biết có lỗi (PSR-18 §3).

Cài đặt

composer require nextpdf/server

Ràng buộc một transport. Hướng dẫn này sử dụng create_pdf, add_text và output_pdf. Cả ba công cụ đều thuộc Core.

Tổng quan khái niệm

Khi một lệnh gọi công cụ thất bại, nó sẽ trả về kết quả lỗi. Kết quả đó mang theo một cờ lỗi, một thông báo mà con người có thể đọc được và một mã nếu có. Kết quả thành công không có cờ lỗi và chứa đầu ra bình thường của công cụ. Trong cả hai trường hợp, transport đã gửi yêu cầu và nhận được phản hồi (PSR-18 §p2).

Giữ vòng lặp phòng vệ thật gọn. Gửi lệnh gọi, rồi đọc kết quả. Nếu kết quả là lỗi, hãy ghi nhật ký, phân loại, áp dụng chiến lược khôi phục và không dùng tiếp trạng thái cũ. Nếu không, hãy trích xuất các trường bạn cần và tiếp tục.

Bề mặt API

Công cụ	Vai trò	Bậc rủi ro
`create_pdf`	Mở phiên	An toàn
`add_text`	Ghi văn bản	Thận trọng
`output_pdf`	Kết xuất và trả về PDF	Cần phê duyệt / Xem xét (base64)

Trang Danh mục công cụ là nguồn chuẩn. Các công cụ khả dụng tùy thuộc vào bậc đã cài đặt.

Mã mẫu — bắt đầu nhanh

Chạy luồng thuận lợi (create_pdf → add_text → output_pdf) và kiểm tra từng kết quả. Sau đó, cố ý dùng lại một document_id đã bị hủy với add_text để kích hoạt lỗi phiên. Khôi phục bằng cách tạo một phiên mới và phát lại nội dung.

Mã mẫu — môi trường production

Phân loại lỗi theo danh mục rồi phản hồi tương ứng:

Xác thực đầu vào — có tính xác định. Sửa các đối số, rồi thử lại cùng lệnh gọi đó. Ví dụ: văn bản rỗng, căn lề không hợp lệ, kích thước không dương, khổ trang không xác định, họ phông chữ không xác định.
Phiên — document_id không còn tồn tại. Tạo một phiên mới, rồi phát lại toàn bộ nội dung.
Hệ thống — một ràng buộc về tài nguyên máy chủ, chẳng hạn như giới hạn phiên. Hãy chờ một lúc, rồi thử lại.
Phê duyệt — output_pdf xuất ra một tệp có thể tạm dừng để chờ con người phê duyệt. Đây là một lần tạm dừng quy trình làm việc, không phải lỗi. Chuyển tiếp thử thách và chờ, rồi gọi lại với token xác nhận.

Đừng bao giờ giả định rằng lệnh gọi đã thành công. Đừng bao giờ dùng lại một document_id sau lỗi phiên. Đừng bao giờ gửi output_pdf cho đến khi mọi bước nội dung đã thành công.

Trường hợp biên & điểm cần lưu ý

Phê duyệt không phải là lỗi. Thử thách có con người tham gia (HITL) là một lần tạm dừng. Đừng thử lại trong một vòng lặp dồn dập. Hãy chuyển tiếp thử thách đó tới con người.
Khởi động lại máy chủ. Mọi phiên trong bộ nhớ đều bị xóa, và mọi document_id trước đó đều trở nên không hợp lệ.
Quy trình làm việc dở dang. Nếu add_text thất bại giữa chừng tài liệu, phiên có thể không nhất quán. Cách khôi phục an toàn là tạo một phiên mới, không phải sửa chữa phần dở dang.

Hiệu năng

Không đáng kể. Hướng dẫn này nói về luồng điều khiển, không phải việc kết xuất. Hồ sơ là structural cho mọi đầu ra được tạo ra.

Ghi chú bảo mật

Thông báo lỗi dành cho agent gọi và người vận hành. Đừng hiển thị nguyên văn văn bản lỗi thô của máy chủ cho người dùng cuối không đáng tin cậy. Thay vào đó, hãy hiển thị một thông báo đã được phân loại và làm sạch.

Tuân thủ

Phát biểu	Đặc tả	Điều khoản	reference_id
Transport trả về phản hồi bất kể kết quả.	PSR-18	§p2
Phản hồi vẫn được trả về ngay cả khi trạng thái báo lỗi.	PSR-18	§3

Bối cảnh thương mại

Không áp dụng — tất cả các công cụ đều thuộc Core.

Tính khả dụng của transport

Transport	Khả dụng	Ghi chú
MCP (stdio)	Có	Lỗi đến dưới dạng kết quả công cụ kèm cờ lỗi.
REST	Có	Trạng thái không thuộc 2xx mang theo cùng phần thân lỗi đã được phân loại.
gRPC	Có	Mã trạng thái kèm thông báo kết quả lỗi.

Với mọi transport, hãy xử lý lỗi ở cấp công cụ như một phản hồi bình thường, không phải một lệnh gọi bị bỏ rơi (PSR-18 §3).

Bậc rủi ro HITL

create_pdf là An toàn, add_text là Thận trọng, và output_pdf là Cần phê duyệt, hạ xuống Xem xét ở chế độ base64. Một thao tác ghi tệp đang chờ sẽ xuất hiện dưới dạng thử thách phê duyệt. Vòng lặp xử lý lỗi phải xem đó là một lần tạm dừng, không phải lỗi (Các bậc rủi ro HITL).

Phong bì JSON của cổng xác nhận

Một yêu cầu phê duyệt đang chờ sẽ trả về:

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

Gọi lại chính công cụ đó với _confirmation_token được đặt thành token đó. Nó trả về { "allowed": true }. Để xem luồng đầy đủ, hãy tham khảo output-approval.