محتويات الدورة

اختبار API / متوسط: عقود متفاعلة / الدرس 7

اختبار المخططات والتوافق الاتجاهي

استخدام افتراضات مخطط صريحة وتوقعات المستهلك لتقييم تغير العقد.

وقت القراءة التقريبي: 4 دقيقةتاريخ مراجعة المحتوى
في هذه الصفحة

أهداف الدرس

  • شرح اختلاف اتجاه توافق الطلب والاستجابة.
  • فصل قبول المخطط عن التوافق الدلالي وتوافق العميل.

استخدام المخطط للادعاء الذي يدعمه

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

تحديد اللهجة وسياسة الحقول المجهولة

يعتمد تفسير الكلمات على لهجة المخطط وإعداد المدقق. يتحكم required في وجود حقل الطلب، بينما يتحكم النوع الذي يتضمن null في القيم الموجودة المقبولة؛ وهما قراران مختلفان. قد تقبل الحقول المجهولة أو ترفض أو تهمل وفق سياسة صريحة، ولا يستنتج العميل السياسة من عينة. يعلن مثال JSON شكلا صغيرا لطلب بلهجة 2020-12. يبقى غير قابل للتنفيذ لأن محرك مخطط لم يشغل. قراءة المخطط ليست تنفيذ كل مفرداته.

json مخطط طلب مثبت بقواعد وجود صريحة
{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","required":["bookId"],"properties":{"bookId":{"type":"string","minLength":1},"note":{"type":["string","null"]}},"additionalProperties":false}

يشترط المخطط bookId ويسمح بغياب note أو إرسالها null ويرفض الخصائص غير المعلنة. لم يشغل بمدقق مخطط. يجب أن تدعم الأداة الفعلية اللهجة والمفردات المهيأة.

مقارنة التوافق في الاتجاه الصحيح

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

python فحص نموذج محدود لمجموعات القبول
old_accepted = {"bookId-only", "bookId-and-note"}
new_requiring_note = {"bookId-and-note"}
new_optional_note = {"bookId-only", "bookId-and-note", "bookId-and-null-note"}
assert not old_accepted <= new_requiring_note
assert old_accepted <= new_optional_note
print("request compatibility direction checked")
الناتج المتوقع
request compatibility direction checked

يبين البرنامج المحلي الكامل أن حذف طلب كان صحيحا يخالف وعد التوافق. الأسماء تمثل بيانات تمت مراجعتها ولا يقدم المثال ادعاء عن مخططات عامة أو مولدات عملاء أو خادم عامل.

البحث عن تغيرات تحافظ على الشكل

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

بناء قرار تغيير قابل للمراجعة

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

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

يصير حقل اختياري إلزاميا دون انتقال

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

يمر تغير الوحدة من تأكيدات النوع

لماذا يحدث؟
يبقى الشكل ثابتا ويتغير المعنى.
كيف تصلحه؟
أكد الوحدات والعلاقات الموثقة.
كيف تتجنب تكراره؟
راجع التغيرات الدلالية مع فروق الوثائق.

يوصف المخطط بأنه تحقق منه بعد قراءة فقط

لماذا يحدث؟
لم ينفذ محرك متوافق المفردات المعلنة.
كيف تصلحه؟
سم القراءة بدقة وشغل المدقق المختار مستقلا عند التصريح.
كيف تتجنب تكراره؟
سجل الأداة واللهجة والإعداد وحدود الدليل.

اختبر فهمك

1. تضيف الواجهة status=archived. لماذا قد يفشل عميل قديم؟

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

قد يقبل المستهلك القديم active وpaused فقط أو يستخدم تفرعا شاملا. اختبر عقد المستهلك المدعوم وسلوك البديل. يبقى النوع string فلا يثبت فحصه التوافق. قرر تنسيق الدعم أو إصدار التغيير.

2. هل يسمح required:[note] بغياب note إذا قبل نوعها null؟

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

لا. required يحكم الوجود. قد تقبل null الموجودة وفقا للنوع، لكن الحذف يخالف قائمة required. أنشئ حالات غياب وnull ونص منفصلة وتحقق منها باللهجة المثبتة عندما تتاح أداة مناسبة.

أهم ما تعلمته

  • صلاحية المخطط طبقة واحدة من العقد.
  • يختلف اتجاه توافق الطلب والاستجابة.
  • تكشف أدلة المعنى والمستهلك كسورا تحافظ على الشكل.

المراجع الرسمية