كيفية استخدام مقارنة عقود الاستجابات
- الصق العقد المتوقَّع: استجابة نموذجية معروفة الصحة أو JSON Schema (بصيغة JSON أو YAML).
- الصق الاستجابة الفعلية (أو المخطط الجديد) في حقل «الفعلي» (Actual) المقابل.
- اترك الوضع على الاكتشاف التلقائي، أو افرض وضع المثال أو وضع المخطط.
- اقرأ الحكم والجدول المرتّب حسب الخطورة؛ تتطلب الصفوف الكاسرة رفع رقم الإصدار أو إصلاحاً.
مزايا مقارنة عقود الاستجابات
- ثلاثة أوضاع: مثال مقابل استجابة، وJSON Schema مقابل استجابة، ومخطط مقابل مخطط
- كاسر: الحقول المحذوفة، وتغييرات الأنواع، وتحوّل قيمة إلى null، والخصائص المطلوبة الجديدة، وقيم enum المحذوفة، والتحوّل من مطلوب إلى اختياري
- محفوف بالمخاطر: توسّع enum، وتغييرات format/pattern، والتحوّل من integer إلى number، والقيود المشدَّدة، وبدائل oneOf/anyOf الجديدة
- آمن: الحقول الاختيارية المضافة والقيود المخفَّفة
- تُقارَن عناصر المصفوفات بالشكل المتوقَّع للعنصر مع دمج الفروق المتكررة
- حكم مع الأعداد وجدول فروق قابل للتنزيل (المسار والتغيير والمتوقَّع والفعلي)
مثال على مقارنة عقود الاستجابات
استجابة طلبية بعد تغيير في الواجهة الخلفية
الإدخال:
Expected: { "id": 1042, "customer": { "email": "layla@example.com" }, "total": 39.98, "createdAt": "2026-09-01T10:00:00Z" }
Actual: { "id": "1042", "customer": { "tier": "gold" }, "total": null, "createdAt": "01/09/2026" }النتيجة:
Verdict: Breaking — 3 breaking changes and 1 risky.
breaking · $.id · type-change: Type changed from integer to string.
breaking · $.customer.email · removed-field: Field "email" is missing from the response.
breaking · $.total · value-to-null: Expected a number but the response returned null.
risky · $.createdAt · format-change: Expected a date-time formatted string but got a plain string.
safe · $.customer.tier · added-field: New field "tier" was added.الأسئلة الشائعة حول مقارنة عقود الاستجابات
ما الذي يُعدّ تغييراً كاسراً؟
الحقول المحذوفة، وتغييرات الأنواع، والقيمة التي أصبحت null، والخصائص المطلوبة الجديدة، وقيم enum المحذوفة، والحقول التي لم تعد مضمونة (من مطلوب إلى اختياري).
ما الذي يُعدّ محفوفاً بالمخاطر؟
التغييرات التي قد ترفضها الجهات المستهلكة الصارمة: قيم enum الجديدة، وتغييرات format أو pattern، وتخفيف integer إلى number، والقيود المشدَّدة، وبدائل oneOf/anyOf الجديدة.
ما الذي يُعدّ آمناً؟
الحقول الاختيارية المضافة والقيود المخفَّفة — فالجهات المستهلكة التي تتجاهل الحقول غير المعروفة تواصل العمل.
هل يمكنني مقارنة مخططين؟
نعم. الصق JSON Schema القديم في خانة المتوقَّع والجديد في خانة الفعلي؛ وتكتشف الأداة وضع «مخطط مقابل مخطط» تلقائياً أو عبر محدّد الوضع.
كيف تُقارَن المصفوفات في وضع المثال؟
يُقارَن كل عنصر في المصفوفة الفعلية (حتى 25 عنصراً) بالعنصر الأول من المصفوفة المتوقَّعة، وتُدمج الفروق المتكررة في صف واحد.
ملاحظات تقنية
يستنتج وضع المثال نوعاً لكل قيمة (null وboolean وinteger وnumber وstring وarray وobject) وصيغة للسلاسل النصية (date-time وdate وuuid وemail وurl) بحيث يُبلَّغ عن التاريخ الذي يتغيّر شكله على أنه محفوف بالمخاطر بدلاً من قبوله بصمت. ويُقارَن كل عنصر في المصفوفة الفعلية بالعنصر المتوقَّع الأول، ويُبلَّغ عن الفروق المتطابقة عبر العناصر مرة واحدة بمسار يحتوي على [].
يعيد وضع المخطط استخدام مدقّق JSON Schema ويربط مخالفات الكلمات المفتاحية بدرجات الخطورة: فمخالفات required وtype كاسرة، ومخالفة additionalProperties آمنة (حقل مضاف)، ومخالفات enum وformat وpattern والقيود محفوفة بالمخاطر. أما وضع «مخطط مقابل مخطط» فيجتاز المخططين بالتوازي، بما في ذلك nullable وenum وformat والقيود وقوائم required وadditionalProperties وitems والكلمات المفتاحية للتركيب (composition).