รูปแบบการจัดการข้อผิดพลาดของ Go API เพื่อการตอบกลับที่ชัดเจนและสอดคล้อง

ทำไมข้อผิดพลาด API ที่ไม่สอดคล้องกันทำให้ไคลเอนต์หงุดหงิด\n\nเมื่อแต่ละ endpoint รายงานความล้มเหลวแตกต่างกัน ไคลเอนต์จะหยุดเชื่อถือ API ของคุณ เส้นทางหนึ่งคืน { error: not found } อีกเส้นทางคืน { message: missing } และอีกเส้นทางหนึ่งส่งข้อความธรรมดา แม้ว่าความหมายจะใกล้เคียงกัน แต่โค้ดฝั่งไคลเอนต์ต้องเดาว่าเกิดอะไรขึ้น\n\nต้นทุนจะปรากฏอย่างรวดเร็ว ทีมสร้างตรรกะการแยกวิเคราะห์ที่เปราะบางและเพิ่มกรณีพิเศษต่อ endpoint การ retry เสี่ยงเพราะไคลเอนต์ไม่สามารถบอกได้ว่า "ลองใหม่ภายหลัง" ต่างจาก "ข้อมูลของคุณผิด" ตั๋วซัพพอร์ตเพิ่มขึ้นเพราะข้อความที่เห็นคลุมเครือ และทีมของคุณไม่สามารถจับคู่กับบรรทัด log ฝั่งเซิร์ฟเวอร์ได้ง่าย\n\nสถานการณ์ที่พบบ่อย: แอปมือถือเรียกสาม endpoint ระหว่างการสมัครใช้งาน ตัวแรกคืน HTTP 400 พร้อมแผนที่ข้อผิดพลาดระดับฟิลด์ ตัวที่สองคืน HTTP 500 พร้อมสตริง stack trace และตัวที่สามคืน HTTP 200 พร้อม { ok: false } ทีมแอปส่งสามตัวจัดการข้อผิดพลาดต่างกัน และทีมแบ็กเอนด์ของคุณยังคงได้รับรายงานอย่าง "การสมัครใช้งานล้มเหลวเป็นครั้งคราว" โดยไม่มีเบาะแสชัดเจนว่าจะเริ่มจากตรงไหน\n\nเป้าหมายคือสัญญาที่คาดเดาได้เดียว ไคลเอนต์ควรอ่านได้อย่างเชื่อถือว่าเกิดอะไรขึ้น ทำให้รู้ว่าเป็นความผิดของใคร ควร retry หรือไม่ และมี request ID ที่พวกเขาสามารถวางในตั๋วซัพพอร์ตได้\n\nหมายเหตุขอบเขต: โฟกัสที่ JSON HTTP APIs (ไม่ใช่ gRPC) แต่แนวคิดเดียวกันใช้ได้กับทุกที่ที่คุณส่งข้อผิดพลาดกลับไปยังระบบอื่น\n\n## เป้าหมายง่าย ๆ: สัญญาเดียวที่ทุก endpoint ปฏิบัติตาม\n\nเลือกสัญญาเดียวที่ชัดเจนสำหรับข้อผิดพลาดและบังคับให้ทุก endpoint ปฏิบัติตาม "สอดคล้อง" หมายถึงรูปแบบ JSON เดียวกัน ความหมายของฟิลด์เดียวกัน และพฤติกรรมเดียวกันไม่ว่า handler ใดจะล้มเหลว เมื่อทำเช่นนั้น ไคลเอนต์จะหยุดเดาและเริ่มจัดการข้อผิดพลาด\n\nสัญญาที่เป็นประโยชน์ช่วยให้ไคลเอนต์ตัดสินใจว่าควรทำอะไรต่อ สำหรับแอปส่วนใหญ่ การตอบข้อผิดพลาดควรตอบสามคำถาม:\n\n- ฉันจะแก้ไขข้อมูลนำเข้าได้ไหม?\n- ควรลองอีกครั้งภายหลังไหม?\n- ฉันจำเป็นต้องติดต่อซัพพอร์ตหรือไม่?\n\nชุดกฎปฏิบัติได้:\n\n- รูปแบบการตอบเดียวสำหรับข้อผิดพลาดทั้งหมด\n- นโยบายสถานะโค้ดเดียวกัน (ประเภทข้อผิดพลาดเดียวกันแมปเป็นสถานะ HTTP เดียวกัน)\n- นโยบายข้อความที่ปลอดภัยเดียวกัน (อะไรที่ผู้ใช้เห็นได้กับอะไรที่เก็บเป็นภายใน)\n- จุดเชื่อมโยงสำหรับการสัมพันธ์ (request ID คืนกลับเพื่อให้ซัพพอร์ตค้นหาความล้มเหลวได้)\n\nตัดสินใจก่อนว่าต้องห้ามไม่ให้ปรากฏอะไรในคำตอบ รายการ "ห้าม" ทั่วไปรวมถึงชิ้นส่วน SQL, stack traces, ชื่อโฮสต์ภายใน, ความลับ และสตริงข้อผิดพลาดดิบจาก dependency\n\nรักษาการแยกให้ชัดเจน: ข้อความสั้นสำหรับผู้ใช้ (ปลอดภัย สุภาพ และปฏิบัติได้) และรายละเอียดภายใน (ข้อผิดพลาดเต็ม, stack, และบริบท) เก็บไว้ในบันทึก ตัวอย่างเช่น “ไม่สามารถบันทึกการเปลี่ยนแปลงของคุณ โปรดลองอีกครั้ง” ปลอดภัย ในขณะที่ “pq: duplicate key value violates unique constraint users_email_key” ไม่ปลอดภัย\n\nเมื่อทุก endpoint ปฏิบัติตามสัญญาเดียวกัน ไคลเอนต์สามารถสร้างตัวจัดการข้อผิดพลาดเดียวและนำกลับมาใช้ซ้ำได้ทุกที่\n\n## กำหนดสกีมาการตอบข้อผิดพลาดที่ไคลเอนต์พึ่งพาได้\n\nไคลเอนต์จะจัดการข้อผิดพลาดได้สะอาดก็ต่อเมื่อทุก endpoint ตอบในรูปแบบเดียวกัน เลือกซอง JSON เดียวและรักษาให้คงที่\n\nค่าเริ่มต้นปฏิบัติได้คือตัว error บวก request_id บนระดับบนสุด:\n\n```json

{ "error": { "code": "VALIDATION_FAILED", "message": "Some fields are invalid.", "details": { "fields": { "email": "must be a valid email address" } } }, "request_id": "req_01HV..." } \n\nสถานะ HTTP ให้หมวดกว้าง (400, 401, 409, 500) ส่วน `error.code` ที่อ่านได้โดยเครื่องจะให้กรณีเฉพาะที่ไคลเอนต์สามารถแยกทางได้ การแยกนี้สำคัญเพราะปัญหาหลายอย่างอาจแชร์สถานะเดียวกัน แอปมือถืออาจแสดง UI ต่างกันสำหรับ `EMAIL_TAKEN` กับ `WEAK_PASSWORD` แม้ทั้งสองจะเป็น `400`\n\nเก็บ `error.message` ให้ปลอดภัยและเป็นมิตรกับคน มันควรช่วยผู้ใช้แก้ปัญหา แต่ไม่ควรรั่วรายละเอียดภายใน (SQL, stack traces, ชื่อผู้ให้บริการ, เส้นทางไฟล์)\n\nฟิลด์เสริมมีประโยชน์เมื่อยังคงคาดเดาได้:\n\n- ข้อผิดพลาดการตรวจสอบ: `details.fields` เป็นแผนที่จากฟิลด์ไปยังข้อความ\n- ขีดจำกัดอัตราหรือปัญหาชั่วคราว: `details.retry_after_seconds`\n- คำแนะนำเพิ่มเติม: `details.docs_hint` เป็นข้อความธรรมดา (ไม่ใช่ URL)\n\nเพื่อความเข้ากันได้ย้อนหลัง ให้ถือว่า `error.code` เป็นส่วนหนึ่งของสัญญา API ของคุณ เพิ่มรหัสใหม่ได้โดยไม่เปลี่ยนความหมายเก่า และเพิ่มเฉพาะฟิลด์ optionals สมมติว่าไคลเอนต์จะเมินฟิลด์ที่ไม่รู้จัก\n\n## ข้อผิดพลาดแบบ typed ใน Go: โมเดลที่ชัดเจนสำหรับ handlers ของคุณ\n\nการจัดการข้อผิดพลาดจะยุ่งเมื่อแต่ละ handler คิดวิธีสื่อความล้มเหลวเอง ชุดข้อผิดพลาด typed เล็ก ๆ แก้ปัญหานั้น: handler คืนค่า error types ที่รู้จัก และชั้นตอบสนองเดียวจะแปลงพวกมันเป็นคำตอบที่สอดคล้องกัน\n\nชุดเริ่มต้นที่ปฏิบัติได้คลุมเกือบทุก endpoint ได้แก่:\n\n- ValidationError (ข้อมูลนำเข้าผิด)\n- NotFoundError (ทรัพยากรไม่พบ)\n- ConflictError (ข้อจำกัด unique, state mismatch)\n- UnauthorizedError (ยังไม่ล็อกอินหรือไม่อนุญาต)\n- InternalError (อย่างอื่นทั้งหมด)\n\nกุญแจคือต้องรักษาเสถียรภาพในระดับบนสุด แม้สาเหตุรากจะเปลี่ยน คุณสามารถห่อสาเหตุระดับต่ำกว่า (SQL, เครือข่าย, การแยกวิเคราะห์ JSON) โดยยังคงคืนประเภทสาธารณะเดียวกันที่ middleware ตรวจจับได้\n\ngo type NotFoundError struct { Resource string ID string Err error // private cause }

func (e NotFoundError) Error() string { return "not found" } func (e NotFoundError) Unwrap() error { return e.Err } json { "request_id": "req_01HV9N2K6Q7A3W1J9K8B", "error": { "code": "VALIDATION_FAILED", "message": "Some fields need attention.", "details": { "fields": { "email": "must be a valid email address" } } } } json { "request_id": "req_01HV9N3C2D0F0M3Q7Z9R", "error": { "code": "ALREADY_EXISTS", "message": "A customer with this email already exists." } } json { "request_id": "req_01HV9N3X8P2J7T4N6C1D", "error": { "code": "TEMPORARILY_UNAVAILABLE", "message": "We could not save your request right now. Please try again." } } ```\n\nเมื่อมีสัญญาเดียว ไคลเอนต์ตอบสนองสม่ำเสมอ:\n\n- 400: ทำเครื่องหมายฟิลด์โดยใช้ \n- 409: แนะนำผู้ใช้ไปยังขั้นตอนถัดไปที่ปลอดภัย\n- 503: ขอให้ retry และแสดง เป็น ID สำหรับซัพพอร์ต\n\nสำหรับซัพพอร์ต เดียวกันเป็นเส้นทางที่เร็วที่สุดไปยังสาเหตุจริงใน logs ภายใน โดยไม่เปิดเผย stack traces หรือข้อผิดพลาดฐานข้อมูล\n\n## กับดักทั่วไปที่ทำให้การจัดการข้อผิดพลาดแย่ลง\n\nวิธีที่เร็วที่สุดที่จะทำให้ไคลเอนต์รำคาญคือทำให้พวกเขาต้องเดา หาก endpoint หนึ่งคืน และอีก endpoint คืน ไคลเอนต์ทุกตัวจะกลายเป็นกองของกรณีพิเศษ และบักจะหลบซ่อนเป็นเวลาหลายสัปดาห์\n\nข้อผิดพลาดบางอย่างที่พบบ่อย:\n\n- คืน HTTP 200 พร้อมข้อผิดพลาดใน body หรือสลับสกีมาข้อผิดพลาดหลายแบบข้าม endpoint\n- เปิดเผยรายละเอียดภายในในข้อความผู้ใช้ เช่น ข้อผิดพลาด SQL, stack traces, IPs, ชื่อโฮสต์ของ dependency หรือเส้นทางไฟล์\n- ใช้ข้อความภาษามนุษย์เป็นตัวระบุเดียว แทนรหัสที่เสถียรที่ไคลเอนต์จะอ้างอิง\n- เปลี่ยนรหัสข้อผิดพลาดโดยไม่ระมัดระวัง (หรือใช้รหัสเดียวกันกับปัญหาต่างกัน) ทำให้ไคลเอนต์ที่เขียนตามพฤติกรรมเก่าพัง\n- เพิ่ม เฉพาะเมื่อเกิดข้อผิดพลาด ทำให้ไม่สามารถเชื่อมโยงรายงานผู้ใช้กับการเรียกที่สำเร็จซึ่งอาจกระตุ้นปัญหาในภายหลังได้\n\nการรั่วไหลของรายละเอียดภายในเป็นกับดักที่ง่ายที่สุดที่จะตก หลายครั้ง handler คืน เพราะสะดวก แล้วชื่อ constraint หรือข้อความจากบุคคลที่สามไปจบใน production responses เก็บข้อความสำหรับผู้ใช้ให้ปลอดภัยและสั้น และใส่สาเหตุโดยละเอียดไว้ใน logs\n\nการพึ่งพาข้อความเพียงอย่างเดียวเป็นปัญหาที่แอบสะสม หากไคลเอนต์ต้อง parse ประโยคภาษาอังกฤษเช่น “email already exists” คุณจะไม่สามารถเปลี่ยนคำพูดโดยไม่ทำให้ตรรกะพัง รหัสข้อผิดพลาดที่เสถียรให้คุณปรับข้อความ แปลมัน และยังรักษาพฤติกรรมให้คงที่\n\nถือว่ารหัสข้อผิดพลาดเป็นส่วนหนึ่งของสัญญาสาธารณะของคุณ หากจำเป็นต้องเปลี่ยน ให้เพิ่มรหัสใหม่และรักษารหัสเดิมให้ทำงานไประยะหนึ่ง แม้ทั้งสองจะแมปไปยังสถานะ HTTP เดียวกัน\n\nสุดท้าย ให้รวมฟิลด์ เดียวกันในทุกการตอบกลับ ไม่ว่าจะสำเร็จหรือไม่ เมื่อผู้ใช้พูดว่า “มันทำงานแล้วแล้วพัง” ID เดียวมักจะช่วยประหยัดเวลาเดาวิธีการได้มาก\n\n## เช็คลิสต์ด่วนก่อนปล่อยของ\n\nก่อนปล่อย ทำการตรวจสอบความสอดคล้องอย่างรวดเร็ว:\n\n- รูปร่างข้อผิดพลาดเดียวทุกที่ ทุก endpoint คืนช่อง JSON เดียวกัน (เช่น: , , )\n- รหัสข้อผิดพลาดที่เสถียรและครอบคลุม เก็บรหัสสั้นและตรงไปตรงมา (, , , ) เพิ่มการทดสอบเพื่อป้องกันไม่ให้ handlers คืนรหัสไม่รู้จักโดยไม่ได้ตั้งใจ\n- กฎการแมปสถานะเดียวกัน ตัดสินใจว่าแต่ละประเภทข้อผิดพลาดแมปเป็นสถานะ HTTP ใด และใช้มันในที่เดียวร่วมกัน\n- request ID สองทาง ส่ง เสมอและบันทึกมันสำหรับทุกคำขอ รวมทั้ง panic และ timeout\n- ข้อความที่ปลอดภัยเป็นค่าเริ่มต้น ข้อความที่เห็นโดยผู้ใช้ควรสั้น ชัดเจน และปฏิบัติได้ ห้าม stack traces, ข้อผิดพลาด SQL, หรือนามผู้ขาย\n\nหลังจากนั้น ตรวจสอบตัวอย่าง endpoint ด้วยมือ ลองทำให้เกิดข้อผิดพลาดการตรวจสอบ ข้อผิดพลาดทรัพยากรไม่พบ และข้อผิดพลาดไม่คาดคิด หากการตอบกลับดูต่างกันข้าม endpoints (ฟิลด์เปลี่ยน รหัสสถานะเบี่ยงเบน ข้อความเผยข้อมูลภายใน) ให้แก้ pipeline ร่วมก่อนเพิ่มฟีเจอร์ต่อ\n\nกฎปฏิบัติ: ถ้าข้อความใดช่วยผู้โจมตีหรือสับสนผู้ใช้ปกติ ข้อความนั้นควรอยู่ใน logs ไม่ใช่ในการตอบกลับ\n\n## ขั้นตอนถัดไป: มาตรฐานเดี๋ยวนี้และรักษาให้สม่ำเสมอต่อไป\n\nเขียนสัญญาข้อผิดพลาดที่คุณต้องการให้ทุก endpoint ปฏิบัติตาม แม้ API จะใช้งานอยู่แล้วก็ตาม สัญญาร่วม (สถานะ, รหัสข้อผิดพลาดที่เสถียร, ข้อความที่ปลอดภัย, และ request_id) เป็นวิธีที่เร็วที่สุดที่จะทำให้ข้อผิดพลาดคาดเดาได้สำหรับไคลเอนต์\n\nจากนั้นย้ายแบบค่อยเป็นค่อยไป เก็บ handlers เดิมไว้ แต่ส่งความล้มเหลวของพวกมันผ่าน mapper เดียวที่แปลงข้อผิดพลาดภายในเป็นรูปแบบการตอบสาธารณะของคุณ นี่ปรับปรุงความสอดคล้องโดยไม่ต้อง rewrite ครั้งใหญ่ และป้องกันไม่ให้ endpoint ใหม่คิดรูปแบบใหม่\n\nรักษาคลังรหัสข้อผิดพลาดขนาดเล็กและถือว่าเป็นส่วนของ API เมื่อใครต้องการเพิ่มรหัสใหม่ ให้ตรวจสอบสั้น ๆ: มันใหม่จริงหรือไม่? ชื่อชัดเจนหรือไม่? และแมปไปยังสถานะ HTTP ถูกต้องหรือไม่?\n\nเพิ่มการทดสอบไม่กี่อย่างที่จะจับการเบี่ยงเบน:\n\n- ทุกการตอบข้อผิดพลาดมี .\n- รหัสสถานะตรงกับประเภทข้อผิดพลาด (ไม่ใช่กับข้อความข้อผิดพลาด).\n- มีอยู่และมาจากคลังรหัส.\n- ปลอดภัยและไม่รวมรายละเอียดภายใน.\n- ข้อผิดพลาดไม่รู้จักย้อนกลับเป็น 500 พร้อมข้อความทั่วไป.\n\nถ้าคุณกำลังสร้างแบ็กเอนด์ Go ตั้งแต่เริ่ม การล็อกสัญญาให้เร็วช่วยได้มาก ตัวอย่างเช่น Koder.ai (koder.ai) รวมโหมดวางแผนที่คุณสามารถกำหนดข้อบังคับเช่นสกีมาข้อผิดพลาดและคลังรหัสล่วงหน้า แล้วรักษา handlers ให้สอดคล้องเมื่อตัว API เติบโตขึ้น.