التحقق من الصحة ومعالجة الأخطاء

يُحكَم على واجهة API من ردود الإخفاق لديها أكثر بكثير مما يُحكَم عليها من ردود النجاح. المسار الطبيعي سهل: كُتب أولاً، واختُبر أولاً، وعُرض أولاً. أما الأخطاء فتظهر في بيئة الإنتاج، عند عميل لا تعرفونه، في موقف لم يتوقعه أحد، وفي تلك اللحظة تحديداً تتكشف جودة الواجهة.

العَرَض المألوف هو مجموعة من التناقضات. معرّف غير موجود يُرجع 500 مع صفحة خطأ HTML من Spring. حقل إلزامي مفقود يُرجع 400 ببنية Spring الافتراضية غير المقروءة. تعارض في المنطق الوظيفي يُرجع 200 مع {"succes": false}. مطوّر مستعجل يضيف try/catch في متحكم، وآخر يضيف @ResponseStatus على استثناء، وثالث يُرجع Map. بعد ستة أشهر يكون فريق العميل قد كتب شيفرة مختلفة لكل endpoint، ولا أحد يجرؤ بعد ذلك على تغيير أي شيء.

يقوم الخروج من هذا المأزق على قرارين. الأول: التحقق من المدخلات عند حدود التطبيق، بشكل تصريحي، حتى لا تصل أي بيانات مشبوهة إلى الخدمة. والثاني: مركزة تحويل الاستثناءات إلى ردود HTTP في مكان واحد، وبصيغة واحدة. ويوفر Spring 6 هذه الصيغة: ProblemDetail، وهو تنفيذ RFC 9457.

سنطبّق الأمرين على biblio-api، على نقاط النهاية التي بُنيت في الدروس السابقة.