جودة البرمجيات / متوسط: أدلة المنتج المتكامل / الدرس 7

عقود API والأخطاء والطلبات المتكررة

اختبر ما يتجاوز رموز الحالة. ابنِ أدلة على التحقق من الطلب ومعنى الاستجابة وحدود الصلاحية ومنع الأثر المكرر، باستخدام API تسجيل افتراضية في بيئة مضبوطة.

وقت القراءة التقريبي: 4 دقيقةتاريخ مراجعة المحتوى 2026-10-23

في هذه الصفحة

أهداف الدرس

اشتقاق اختبارات العقود من سلوك API المتفق عليه.
التحقق من الاستجابة والآثار المحفوظة معاً.
تصميم حالات سلبية وإعادة محاولة بأمان.

العقد يشمل المعنى

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

حالة محلولة: الإنشاء والقراءة

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

text عقد تطبيق توضيحي وليس فرضاً عاماً لرموز الحالة

الحالة | شرط الطلب | الملاحظة المتوقعة
إنشاء | متعلم ودورة صالحان | 201 متفق عليه؛ معرف؛ مورد واحد
قراءة | المعرف المعاد بواسطة المالك | 200؛ حقول تجارية مطابقة
غير صالح | course_id غائب | خطأ تحقق متفق عليه؛ لا مورد
ممنوع | مورد متعلم آخر | رفض متفق عليه؛ لا حقول خاصة

تشمل التحققات الهوية والآثار بجانب الحالة والبنية.

الاستجابات السلبية تحتاج تحققات صريحة

اختبر الحقول الغائبة والأنواع الخاطئة والمعرفات المجهولة والانتقالات الممنوعة والفاعلين غير المخولين مع صلاحية بقية البيانات. افحص بقاء الحالة دون تغيير وعودة خطأ مفيد متسق بلا تفاصيل مكدس داخلي. ميّز غير المسجل من المسجل الذي يفتقر للصلاحية؛ فقد يتعمد العقد إخفاء وجود المورد. ليست استجابة 500 لمدخل مشوه نتيجة تحقق متوقعة. لا تعتبر أي رمز غير ناجح نجاحاً؛ فقد يجعل تعطل الخدمة جميع الاختبارات السلبية تبدو ناجحة.

حالة محلولة: مهلة غامضة وإعادة محاولة

افترض أن مسار التسجيل يعرّف مفتاح عدم تكرار أثر على مستوى التطبيق. جهّز طلباً تنجح كتابته لكن يحجب بديل محلي استجابته عمداً. أعد الطلب نفسه بالمفتاح نفسه. توقّع هوية التسجيل الأصلية وعدم استهلاك مقعد ثانٍ. ويجب أن تتبع إعادة المفتاح مع دورة مختلفة سلوك التعارض المتفق عليه. لا تصبح POST بطبيعتها عديمة تكرار الأثر لأن التطبيق أضاف مفتاحاً. افحص نطاق المفتاح وافتراض مدة الاحتفاظ وآثار التخزين، لا مجرد تطابق جسمي الاستجابة.

فصل عقود المزود من المحاكاة المحلية

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

الأخطاء الشائعة وإصلاحها

التحقق من HTTP 200 فقط

لماذا يحدث؟: الخلط بين نجاح النقل وصحة السلوك التجاري.
كيف تصلحه؟: التحقق من الهوية والحقول والقيم والآثار المحفوظة.
كيف تتجنب تكراره؟: مراجعة وجود مرجع حكم معنوي لكل اختبار API.

قبول أي خطأ في اختبار سلبي

لماذا يحدث؟: عدم تحديد نمط الإخفاق المتوقع.
كيف تصلحه؟: التحقق من فئة الخطأ المتفق عليها وثبات الحالة.
كيف تتجنب تكراره؟: الاحتفاظ بحالة أساس ناجحة في البيئة المضبوطة نفسها.

إهمال الآثار المكررة عند إعادة المحاولة

لماذا يحدث؟: فحص تطابق الاستجابات فقط.
كيف تصلحه؟: فحص عدد الموارد والمقاعد وسلوك المفتاح.
كيف تتجنب تكراره؟: إدراج سيناريو استجابة غامضة ضمن العقد.

اختبر فهمك

1. يعيد طلب مشوه 500 وينجح الاختبار لأنه ليس 200. أصلح مرجع الحكم.

اعرض الحل المشروح

تحقق من حالة التحقق المتفق عليها ورمز خطأ قابل للمعالجة آلياً، ومن عدم إنشاء تسجيل. يجب أن يفشل الاختبار عند 500 لأنه خطأ خادم غير متوقع رغم عدم نجاح الطلب. أدرج طلباً صالحاً ضابطاً لكشف تعطل الخدمة العام.

2. ما الذي يميز إنشاءً متكرراً آمناً عن استجابتين متطابقتين؟