การจัดการข้อผิดพลาดในเวิร์กโฟลว์ NextPDF Connect

ภาพรวมโดยสังเขป

สร้างเวิร์กโฟลว์ Connect ให้ทนต่อความล้มเหลว โดยตรวจสอบความถูกต้องของผลลัพธ์เครื่องมือทุกรายการ ปิดเซสชันที่ล้มเหลว แล้วลองใหม่จากสถานะที่เริ่มต้นใหม่ เครื่องมือที่ล้มเหลวจะคืนค่าผลลัพธ์ข้อผิดพลาดแบบมีโครงสร้าง ให้จัดการผลลัพธ์นั้นเสมือนเป็นการตอบกลับปกติ ไม่ใช่ความล้มเหลวของ transport PHP Standards Recommendation (PSR)-18 แยกแยะในแนวเดียวกัน คือมีการคืนค่าการตอบกลับแม้สถานะจะระบุว่าเป็นข้อผิดพลาด (PSR-18 §3)

การติดตั้ง

composer require nextpdf/server

ผูก transport ให้เรียบร้อย สูตรนี้ใช้ create_pdf, add_text และ output_pdf เครื่องมือทั้งสามรายการเป็น Core

ภาพรวมเชิงแนวคิด

การเรียกใช้เครื่องมือที่ล้มเหลวจะคืนค่าผลลัพธ์ข้อผิดพลาด ผลลัพธ์นี้มีแฟล็กข้อผิดพลาด ข้อความที่อ่านเข้าใจได้ และรหัสเมื่อมีให้ใช้งาน ผลลัพธ์ที่สำเร็จจะไม่มีแฟล็กข้อผิดพลาดและมีเอาต์พุตปกติของเครื่องมือ ในทั้งสองกรณี transport ได้ส่งคำขอและได้รับการตอบกลับแล้ว (PSR-18 §p2)

ทำให้ลูปเชิงป้องกันสั้นและกระชับ ส่งการเรียกใช้แล้วอ่านผลลัพธ์ หากผลลัพธ์เป็นข้อผิดพลาด ให้บันทึกล็อก จำแนกประเภท ใช้กลยุทธ์การกู้คืน และหยุดใช้สถานะที่ล้าสมัย หากไม่พบข้อผิดพลาด ให้ดึงฟิลด์ที่ต้องการออกมาแล้วดำเนินการต่อ

ส่วนติดต่อ API

เครื่องมือ	บทบาท	ระดับความเสี่ยง
`create_pdf`	เปิดเซสชัน	Safe
`add_text`	เขียนข้อความ	Caution
`output_pdf`	เรนเดอร์และคืนค่า PDF	ต้องอนุมัติ / ตรวจสอบ (base64)

หน้า แคตตาล็อกเครื่องมือ เป็นแหล่งอ้างอิงที่ถูกต้อง เครื่องมือที่พร้อมใช้งานขึ้นอยู่กับระดับที่ติดตั้งไว้

ตัวอย่างโค้ด — เริ่มต้นใช้งานอย่างรวดเร็ว

รันเส้นทางปกติที่ไม่มีข้อผิดพลาด (create_pdf → add_text → output_pdf) แล้วตรวจสอบผลลัพธ์แต่ละรายการ จากนั้นจงใจนำ document_id ที่ถูกทำลายไปแล้วมาใช้ซ้ำกับ add_text เพื่อทำให้เกิดข้อผิดพลาดของเซสชัน กู้คืนด้วยการสร้างเซสชันใหม่และเล่นเนื้อหาซ้ำ

ตัวอย่างโค้ด — การใช้งานจริง

จำแนกข้อผิดพลาดตามหมวดหมู่ แล้วตอบสนองให้สอดคล้องกัน:

การตรวจสอบความถูกต้องของอินพุต — ผลลัพธ์กำหนดได้แน่นอน แก้ไขอาร์กิวเมนต์ แล้วลองเรียกใช้ครั้งเดิมซ้ำ ตัวอย่าง: ข้อความว่างเปล่า การจัดแนวที่ไม่ถูกต้อง ขนาดที่ไม่เป็นบวก ขนาดหน้าที่ไม่รู้จัก ตระกูลฟอนต์ที่ไม่รู้จัก
เซสชัน — document_id ไม่มีอยู่อีกต่อไป ให้สร้างเซสชันใหม่ แล้วเล่นเนื้อหาทั้งหมดซ้ำ
ระบบ — ข้อจำกัดด้านทรัพยากรของเซิร์ฟเวอร์ เช่น ขีดจำกัดของเซสชัน ให้หน่วงเวลาแบบถอยกลับ แล้วลองใหม่
การอนุมัติ — output_pdf ไปยังไฟล์อาจหยุดชั่วคราวเพื่อรอการอนุมัติจากมนุษย์ กรณีนี้เป็นการหยุดชั่วคราวของเวิร์กโฟลว์ ไม่ใช่ความล้มเหลว ส่งต่อ challenge และรอ จากนั้นเรียกใช้ใหม่พร้อมโทเค็นยืนยัน

ห้ามสันนิษฐานว่าการดำเนินการสำเร็จ ห้ามนำ document_id มาใช้ซ้ำหลังเกิดข้อผิดพลาดของเซสชัน และห้ามส่ง output_pdf จนกว่าขั้นตอนเนื้อหาทุกขั้นจะสำเร็จ

กรณีขอบและข้อควรระวัง

การอนุมัติไม่ใช่ข้อผิดพลาด challenge แบบ human-in-the-loop (HITL) เป็นการหยุดชั่วคราว อย่าลองใหม่ในลูปที่วนถี่ ให้ส่งต่อไปยังมนุษย์
การรีสตาร์ทเซิร์ฟเวอร์ เซสชันในหน่วยความจำทั้งหมดจะถูกล้าง และค่า document_id ก่อนหน้านี้ทั้งหมดจะใช้งานไม่ได้
เวิร์กโฟลว์ที่ไม่เสร็จสมบูรณ์ หาก add_text ล้มเหลวกลางคันระหว่างสร้างเอกสาร เซสชันอาจอยู่ในสถานะไม่สอดคล้องกัน การกู้คืนที่ปลอดภัยคือการเริ่มเซสชันใหม่ ไม่ใช่การซ่อมแซมเพียงบางส่วน

ประสิทธิภาพ

ผลกระทบน้อยจนแทบไม่มีนัยสำคัญ สูตรนี้ครอบคลุมการควบคุมลำดับการทำงาน ไม่ใช่การเรนเดอร์ โปรไฟล์เป็น structural สำหรับเอาต์พุตที่สร้างขึ้นทุกรายการ

หมายเหตุด้านความปลอดภัย

ข้อความข้อผิดพลาดมีไว้สำหรับเอเจนต์ที่เรียกใช้และผู้ดูแลระบบ อย่าส่งข้อความข้อผิดพลาดดิบจากเซิร์ฟเวอร์ให้ผู้ใช้ปลายทางที่ไม่น่าเชื่อถือเห็นโดยตรง ให้แสดงข้อความที่จำแนกประเภทและผ่านการกรองแล้วแทน

ความสอดคล้องตามข้อกำหนด

ข้อความระบุ	ข้อกำหนด	ข้อ	รหัสอ้างอิง (reference_id)
transport คืนค่าการตอบกลับโดยไม่คำนึงถึงผลลัพธ์	PSR-18	§p2
มีการคืนค่าการตอบกลับแม้ในสถานะที่เป็นข้อผิดพลาด	PSR-18	§3

บริบทเชิงพาณิชย์

ไม่เกี่ยวข้อง — เครื่องมือทั้งหมดเป็น Core

ความพร้อมใช้งานของ transport

การรับส่งข้อมูล (Transport)	พร้อมใช้งาน	หมายเหตุ
MCP (stdio)	ใช่	ข้อผิดพลาดจะมาถึงในรูปของผลลัพธ์เครื่องมือที่มีแฟล็กข้อผิดพลาด
REST	ใช่	สถานะที่ไม่ใช่ 2xx จะมีเนื้อหาข้อผิดพลาดที่จำแนกประเภทแล้วเหมือนกัน
gRPC	ใช่	รหัสสถานะพร้อมข้อความผลลัพธ์ข้อผิดพลาด

สำหรับ transport ทุกแบบ ให้ตรวจสอบข้อผิดพลาดระดับเครื่องมือเสมือนเป็นการตอบกลับปกติ ไม่ใช่การเรียกใช้ที่ถูกทิ้ง (PSR-18 §3)

ระดับความเสี่ยง HITL

create_pdf เป็น Safe, add_text เป็น Caution และ output_pdf เป็น Approval Required โดยจะลดระดับเป็น Review ในโหมด base64 การเขียนไฟล์ที่รอดำเนินการจะปรากฏเป็น approval challenge ลูปการจัดการข้อผิดพลาดต้องจัดการสิ่งนี้เสมือนเป็นการหยุดชั่วคราว ไม่ใช่ความล้มเหลว (ระดับความเสี่ยง HITL)

ซองข้อมูล JSON ของเกตการยืนยัน

การอนุมัติที่รอดำเนินการจะคืนค่า:

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

เรียกใช้เครื่องมือเดิมซ้ำโดยตั้งค่า _confirmation_token เป็นโทเค็นดังกล่าว ระบบจะคืนค่า { "allowed": true } โปรดดู output-approval สำหรับลำดับการทำงานทั้งหมด