اختبار API / أساسي: ملاحظات واجهة موثوقة / الدرس 6
التحقق من عقود الأخطاء وبقاء الحالة دون تغيير
اختبار معلومات فشل مفيدة وثابتة دون تسريب التفاصيل الداخلية أو مساواة كل الأخطاء.
في هذه الصفحة
أهداف الدرس
- التمييز بين مدخل معطوب ورفض المجال ومنع الصلاحية وفشل التبعية.
- فحص بنية تفاصيل المشكلة مع الحالة المحمية وسياسة الإفصاح.
تصنيف الوعد الذي فشل
الأخطاء جزء من عقد الواجهة وليست نصوصا عرضية عند توقف النجاح. يختلف التمثيل المعطوب عن كتاب صحيح غير متاح وعن مستدع بلا توثيق وعن تبعية متوقفة. اختر فئات ثابتة يستطيع العميل التعامل معها دون تحليل جملة بشرية. قد تخفي الخدمة وجود المورد عمدا عن غير المصرح له، لذا يجب اتباع سياسة الإفصاح الموثقة بدلا من طلب أكبر قدر من التفاصيل. يستخدم عقد التدريب حالات مختلقة ولا يستكشف هوية أو موردا حقيقيا.
استخدام المعنى القابل للمعالجة عن قصد
توفر Problem Details تمثيلا معياريا لأخطاء الواجهات، لكنها لا تقرر سياسة التطبيق كاملة. يحدد type فئة المشكلة، ولا ينبغي تحويل الحقول البشرية إلى أهداف تحليل هشة. يجب ألا تناقض حالة الجسم حالة استجابة HTTP الفعلية. يمكن للإضافات حمل تفاصيل تحقق موثقة دون القيم الخاصة أو آثار المكدس. يفحص البرنامج ملاحظة مشكلة خيالية واحدة. رابط المثال المحجوز معرف فقط ولا يجري جلبه أو الاتصال بسجل أو خدمة.
actual_status = 422
problem = {"type": "https://catalog.example.invalid/problems/invalid-page", "title": "Invalid page size", "status": 422, "field": "pageSize"}
assert problem["status"] == actual_status
assert problem["type"].endswith("/invalid-page")
assert problem["field"] == "pageSize"
assert "trace" not in problem
print("problem observation accepted")
problem observation accepted
يفحص البرنامج الكامل شكل التطبيق المختار واتساق الحالة. ليس مدققا شاملا للمعيار، ولا يثبت استخدام استجابة HTTP حقيقية للنوع application/problem+json أو خلوها من كل تفصيل حساس.
اعتبار الرفض انتقالا في الحالة
يجب أن يبقي الطلب المرفوض حالة العمل المحمية دون تغيير ما لم يتوقع أثر ثانوي موثق. قد يكون تسجيل الرفض مشروعا، لكن إنشاء مدخل قبل التحقق ثم إعادة خطأ غير صحيح. التقط ملاحظة صغيرة قبل وبعد، وأدرج حالة صندوق الأحداث أو الإشعارات عندما يقتضي العقد. يستخدم البرنامج الثاني لقطات لقواميس محلية لتوضيح الفحص. لا يثبت تراجع المعاملة أو إلغاء الأثر غير المتزامن أو عزل قاعدة حقيقية؛ فهذه أسئلة تكامل مستقلة ببيانات معتمدة.
from copy import deepcopy
before = {"entries": [{"id": "entry-1", "book": "book-2"}], "notifications": []}
after = deepcopy(before)
response = {"status": 409, "code": "BOOK_ALREADY_LISTED"}
assert response["status"] == 409
assert response["code"] == "BOOK_ALREADY_LISTED"
assert after == before
print("refusal preserves protected state")
refusal preserves protected state
لا يتضمن الرصد المحلي الكامل تعديلا أو إشعارا خارجيا. يثبت مقارنة البيانات المذكورة فقط. اختيار 409 جزء من عقد الإضافة المكررة الخيالي ولا يفرض على كل العمليات المكررة.
فصل الفئات الثابتة عن النص المقروء
يجب ألا يكسر عنوان مترجم أو شرح محسن عميلا يستخدم الفئة الآلية الموثقة. افحص معرفات الخطأ ومسارات الحقول بدقة عندما يضمن العقد ثباتها، وافحص النص البشري من حيث الوجود والسلامة بدلا من علامات الترقيم الاعتباطية. وفي المقابل لا تقبل أي سلسلة بدلا من رمز محدد. تحقق من قدرة العميل على فصل رفض تبعية قابل للمحاولة عن خطأ مدخل دائم. أدرج حالات التحليل والحدود والعلاقات بين الحقول دون اختراع ترتيب أولوية لم يعد به العقد.
حفظ دليل فشل مفيد بأمان
يعرض تقرير الخطأ الحالة والفئة المتوقعة والمرصودة والفرق البنيوي المهم. استبدل الأجسام الحقيقية بإعادة إنتاج مختلقة وتجنب تسجيل ترويسات التفويض والكوكيز ومحتويات السجلات الخاصة. يمكن للتشخيص الداخلي ربط الطلب بمعرف غير سري، لكن تفاصيل المشكلة العامة لا تكشف المكدس أو أسماء البنية التحتية. عند الفشل المتقطع افحص حدود التبعية والتوقيت بدلا من توسيع الأخطاء المقبولة. تفيد إعادة محلية حتمية لخريطة الفئات، لكنها تختلف عن رصد فشل منشور حقيقي.
الأخطاء الشائعة وإصلاحها
يكسر عنوان مترجم اختبار العميل
- لماذا يحدث؟
- يحلل العميل النص البشري بدلا من الفئة الثابتة.
- كيف تصلحه؟
- قارن type أو الرمز الموثق وافحص النص المقروء منفصلا.
- كيف تتجنب تكراره؟
- أدرج تغير اللغة في مراجعة عقد الأخطاء.
ينشئ طلب مرفوض مدخلا
- لماذا يحدث؟
- يحدث التحقق بعد التعديل أو يكون التراجع ناقصا.
- كيف تصلحه؟
- أصلح حدود المعاملة وافحص الآثار المهمة.
- كيف تتجنب تكراره؟
- اشترط مقارنة الحالة قبل وبعد في حالات الرفض.
تختلف حالة الجسم عن حالة HTTP
- لماذا يحدث؟
- تستخدم خريطة الأخطاء مصادر غير متسقة.
- كيف تصلحه؟
- استخرجهما من خريطة مراجعة واحدة واختبر الحد الفعلي.
- كيف تتجنب تكراره؟
- غط كل فئة موثقة وقاعدة إفصاح عامة.
اختبر فهمك
1. تعيد الإضافة المكررة الرمز الصحيح لكنها ترسل إشعارا. هل تنجح؟
اعرض الحل المشروح
لا وفق هذا العقد. يجب ألا تتغير حالة المدخل والإشعارات. أدرج رصد الإشعار في حالة الرفض وافحص حدوث الأثر قبل الرفض. لا تعوض استجابة الخطأ إجراء عمل غير مقصود.
2. يرسل حقلان غير صالحين معا. هل يجب تأكيد ترتيب أخطائهما؟
اعرض الحل المشروح
فقط إذا كان الترتيب جزءا صريحا من العقد. وإلا قارن مسارات الحقول والفئات دون افتراض ترتيب المرور الداخلي. أبق حالات لكل حقل منفردا كي لا يخفي الفشل المجمع حقلا لا يتحقق منه أبدا.
أهم ما تعلمته
- تحتاج عقود الأخطاء معنى آليا ثابتا وسياقا بشريا آمنا.
- يشمل اختبار الرفض الحالة المحمية والآثار المهمة.
- تتطلب فئات الفشل قرارات مختلفة من العميل.