كيف تشخّص أخطاء API في مشروعك خطوة بخطوة؟

إذا عرضت الواجهة «حدث خطأ»، افتح الطلب الذي فشل قبل تعديل الكود. عنوانه وطريقته وبياناته ورمز الاستجابة تخبرك أين تبدأ البحث، ثم يساعدك سجل الخادم على متابعة ما حدث داخله. سنستخدم هذه الأدلة لتشخيص طلب API واحد، مع التفريق بين تعذر الاتصال ورفض الطلب وفشل قراءة الاستجابة.

التقط طلباً واحداً كاملاً

افتح أدوات المطور في المتصفح وتبويب Network، ونفذ الفعل مرة واحدة. احفظ المسار وطريقة HTTP ورمز الاستجابة ونوع محتواها والزمن التقريبي ومعرف تتبع إن وجد. افحص Payload للتأكد من أسماء الحقول وأنواعها. إذا كانت الواجهة تتوقع deviceId والخادم يستقبل device_id، فقد تكون المشكلة اختلاف عقد، لا تعطل قاعدة البيانات.

لا تنشر ملف HAR أو صورة Headers قبل مراجعته؛ فقد يتضمن Cookies أو رموز جلسة أو بيانات عميل. عند طلب المساعدة، استبدل القيم الحساسة وأبقِ البنية التي يحتاجها التشخيص. احفظ نسخة أدلة محدودة في مساحة تطوير مناسبة، ولا تضف السجلات الخام إلى مستودع عام.

استخدم الرمز لتحديد الفحص التالي

هذا الجدول يوجه التحقيق ولا يثبت سبباً وحده. قد تستخدم بعض التطبيقات 404 لإخفاء وجود مورد غير مسموح، وقد يعيد وسيط الاستضافة 502 قبل وصول الطلب للتطبيق. راجع معاني حالات HTTP ثم اقرأ عقد API الذي تعمل عليه، بدلاً من افتراض تطابق كل نظام مع مثال واحد.

مثال تشخيص: رفض حجز متعارض

نفترض أن الواجهة تعرض رسالة عامة بعد إرسال حجز. في Network يظهر أن الطلب وصل إلى POST /api/bookings وأعاد 409. الاستجابة التالية نموذج توضيحي وليست سجلاً من نظام عميل:

{
  "code": "BOOKING_CONFLICT",
  "message": "الفترة المطلوبة غير متاحة",
  "requestId": "demo-req-104"
}

الفحص الأول هو إعادة الطلب ببيانات اختبار وفترة متاحة، ثم بفترة تتداخل مع حجز موجود. إن نجحت الأولى ورُفضت الثانية كما ينص العقد، فالخادم قد يكون يعمل كما ينبغي والمشكلة في ترجمة الرفض إلى رسالة مفيدة. راجع معالج الواجهة: هل يفحص response.ok؟ هل يتوقع error بينما الخادم يعيد message؟

إذا رُفضت الفترة المتاحة أيضاً، استخدم معرف الطلب للعثور على سجل محدود يوضح الجهاز والبداية والنهاية والقرار، دون رموز دخول. افحص المنطقة الزمنية وقاعدة التداخل والبيانات القديمة وحالة الصيانة. لا تحذف الحجوزات لتجعل التجربة تنجح؛ أنشئ بيانات اختبار معروفة تعزل السبب.

ميّز CORS عن فشل التطبيق

إذا منعت سياسة المتصفح قراءة الاستجابة بين أصلين، افحص رسالة Console وطلب OPTIONS إن وجد، وقارن الأصل المسموح بإعداد الخادم. نجاح الاستدعاء من أداة سطر أوامر لا يثبت أن المتصفح سيسمح به، لأن قيود المتصفح جزء مختلف من المسار. لا تعالج المشكلة بإلغاء حماية المتصفح أو استخدام no-cors عندما تحتاج قراءة استجابة API؛ فهذا لا يحول الاستجابة المعتمة إلى بيانات قابلة للاستخدام.

من وثائق Fetch راجع نمط الطلب والاعتماديات وحالة الاستجابة. في تطبيق يستخدم جلسات، تحتاج مراجعة سياسة الأصل والكوكيز وحماية CSRF معاً وفق الإطار. نسخ Header من مثال غير مطابق قد يخفي العرض مؤقتاً ولا يصلح العقد أو إعداد المصادقة.

أعد الطلب الذي فشل وسجّل نتيجة الإصلاح

بعد تحديد السبب، نفذ أصغر تعديل يعالجه، ثم أعد حالة الفشل نفسها وحالة نجاح مجاورة لها. إذا كان الإصلاح تحويل حقل، اختبر قيمة ناقصة ونوعاً غير صحيح أيضاً. وإذا كان توقيتاً، اختبر حدود بداية الفترة ونهايتها. سجّل البيئة وإصدار التطبيق ونتيجة الاختبار، كي لا تتحول عودة الخطأ لاحقاً إلى تحقيق يبدأ من الصفر.

لطلب تشخيص المشروع وإصلاحه، أرسل خطوات إعادة المشكلة والنتيجة المتوقعة ورسالة الخطأ بعد إزالة الأسرار منها، مع الملفات اللازمة لتشغيل الجزء المتأثر. وبعد الإصلاح حدّث عقد API إذا تغير سلوكه، وأضف حالة الفشل إلى سجل الاختبارات.