การจัดการ Error API ด้วย JSON: แนวทาง PostgreSQL สำหรับ REST API

ในโลกของการพัฒนา REST API การที่ระบบส่งข้อผิดพลาด (Error) กลับไปให้ผู้ใช้งานหรือระบบเรียกใช้ (Client) อย่างไม่มีรูปแบบที่แน่นอนถือเป็นปัญหาใหญ่ที่สุดอย่างหนึ่ง ข้อผิดพลาดที่มาจากฐานข้อมูลโดยตรงมักจะมีรูปแบบที่ซับซ้อนและไม่เป็นมิตรต่อการนำไปใช้งาน (Unfriendly)

ในฐานะ Senior Architect เราทราบดีว่าการสร้าง API ที่แข็งแกร่งต้องมีการจัดการข้อผิดพลาดที่สม่ำเสมอ (Consistent) และสามารถคาดเดาได้ (Predictable) การส่ง Error กลับในรูปแบบ JSON ที่มีโครงสร้างชัดเจนจึงเป็นมาตรฐานที่ต้องยึดถือ

หลักการทำงาน: การควบคุม Error จากระดับ PostgreSQL

แม้ว่า API Gateway หรือ Web Framework จะเป็นตัวจัดการการส่ง HTTP Status Code แต่แหล่งที่มาของข้อผิดพลาดส่วนใหญ่มักมาจาก Logic ภายในฐานข้อมูล ซึ่งในกรณีนี้คือ PostgreSQL เราจึงต้องออกแบบฟังก์ชัน (Function) ใน PostgreSQL ด้วยภาษา PL/pgSQL ให้ทำหน้าที่เป็นตัวควบคุมการไหลของข้อมูล (Flow Control) และการแจ้งข้อผิดพลาด

แทนที่จะปล่อยให้ PostgreSQL ส่งข้อผิดพลาดดิบ ๆ ออกมา เราจะใช้ฟังก์ชันที่รับผิดชอบในการตรวจสอบความถูกต้องของข้อมูล (Validation) และหากเกิดข้อผิดพลาด เราจะใช้คำสั่งเพื่อสร้างและส่งคืน (Return) โครงสร้าง JSON ที่กำหนดไว้ล่วงหน้า โดยกำหนดให้ JSON นี้มีองค์ประกอบสำคัญ เช่น error_code, message, และ details

ตัวอย่างการสร้างฟังก์ชัน Error Handling ใน PostgreSQL

ตัวอย่างนี้แสดงฟังก์ชันที่จำลองการตรวจสอบข้อมูล (เช่น การตรวจสอบว่า User ID มีอยู่จริงหรือไม่) และหากล้มเหลว จะส่งคืน JSON Error แทนที่จะปล่อยให้เกิด Exception ธรรมดา

SQL

-- 1. สร้างฟังก์ชันที่ส่งคืน JSONB สำหรับการจัดการ Error ที่เป็นมาตรฐาน
CREATE OR REPLACE FUNCTION api_error_json(p_code TEXT, p_message TEXT, p_details JSONB) RETURNS JSONB AS $$ 
BEGIN
    RETURN jsonb_build_object(
        'success', FALSE,
        'error', jsonb_build_object(
            'code', p_code,
            'message', p_message,
            'details', p_details
        )
    );
END; 
$$ LANGUAGE plpgsql;

-- 2. ตัวอย่างการใช้งาน: ตรวจสอบ User ID และจำลองการส่ง Error
SELECT api_error_json(
    'USER_NOT_FOUND',
    'User ID ที่ระบุไม่ถูกต้อง', 
    jsonb_build_object('requested_id', '999')
);

-- 3. ตัวอย่างการใช้งานสำเร็จ (Success Case)
-- (ในระบบจริงจะมีการ return JSON success แยกต่างหาก)
SELECT jsonb_build_object('success', TRUE, 'data', 'Operation successful');

แนวทางการออกแบบ JSON Error ที่ดี (Best Practices)

เมื่อออกแบบโครงสร้าง JSON Error ควรคำนึงถึงความสามารถในการประมวลผลของ Client (Client Parsability) เสมอ โครงสร้างที่แนะนำควรประกอบด้วย:

• success: Boolean (ควรเป็น FALSE)
• error: Object ที่บรรจุรายละเอียดข้อผิดพลาด
• code: รหัสข้อผิดพลาดเฉพาะของระบบ (เช่น INVALID_INPUT) เพื่อให้ Client สามารถทำ Logic การแก้ไขได้
• message: ข้อความที่อ่านง่ายสำหรับผู้ใช้งาน (Human-readable message)
• details: ข้อมูลเพิ่มเติมเชิงเทคนิค (เช่น ฟิลด์ใดที่ผิดพลาด)

บทสรุป

การจัดการข้อผิดพลาดในระดับฐานข้อมูลด้วย PostgreSQL และการบังคับให้ส่งออกเป็น JSON ที่มีโครงสร้างชัดเจน ไม่เพียงแต่ช่วยให้ API ของคุณดูเป็นมืออาชีพเท่านั้น แต่ยังช่วยลดภาระในการเขียนโค้ดจัดการ Exception ในชั้นแอปพลิเคชัน (Application Layer) ได้อย่างมาก ทำให้ระบบโดยรวมมีความเสถียรและง่ายต่อการบำรุงรักษาในระยะยาว