جودة DevOps / الأساسي: أدلة التسليم وتصميم الحزم / الدرس 4
سلوك API وعقود التوافق
استخدم أدلة API والعقود لكشف تغييرات غير متوافقة قبل التقاء مكونات تسلّم مستقلة.
في هذه الصفحة
أهداف الدرس
- افصل مطابقة المخطط وتوافق المستهلك وصحة الأعمال.
- اربط إصدارات أدلة العقد بهوية المستهلك والمزود.
عرّف ادعاء التوافق
يختبر API تنفيذاً ملموساً عبر حد الطلب، ويصف المخطط الرسائل المسموحة، ويسجل العقد المدفوع بالمستهلك تفاعلات يحتاجها فعلاً ويتحقق من تلبيتها لدى المزود. تتقاطع لكنها تجيب أسئلة مختلفة. قد تطابق استجابة المخطط بعدد حجوزات خاطئ، وقد يرضي المزود مستهلكاً ويكسر آخر. سمّ إصدارات الطرفين وحالات المزود وتركيبات النشر. تفيد أدلة التوافق عندما تطابق الإصدارات التي قد تتعايش أثناء التسليم.
تحقق من المعنى إلى جانب الحالة
حالة HTTP ناجحة وحدها دليل ضعيف. افحص انتقال الحالة المتوقع والحقول المستخدمة والنتائج الدائمة المناسبة. تتحقق الحالات السلبية من الخطأ الموثق دون تعديل حالة محمية. اجعل المصادقة والملكية صريحتين. يفحص المثال حد صفر مقاعد عبر API محلي اصطناعي ويتجنب نقطة عامة. يجب أن يوفر الإعداد ورشته وحسابه المعزولين، ويمكن لفحص منفصل تأكيد عدم استهلاك الطلب المرفوض للسعة.
import { test, expect } from "@playwright/test";
test("zero seats are rejected", async ({ request }) => {
const response = await request.post("/api/reservations", {
data: { workshopId: "owned-workshop", seats: 0 }
});
expect(response.status()).toBe(422);
expect(await response.json()).toMatchObject({ code: "INVALID_SEAT_COUNT" });
});
اضبط baseURL محلياً واعتمادات اختبار عبر البيانات في مشروع Playwright مثبت. يجب أن ينفذ التطبيق الحالة ورمز الخطأ؛ 422 عقد المثال لا قاعدة عامة لكل API. لا تنفذ الدورة أي طلب.
راجع تطور الرسائل بقصد
قد يكسر حذف حقل مطلوب أو تغيير نوعه مستهلكاً منشوراً رغم نجاح اختبارات المزود. غالباً تسهل إضافة حقل اختياري لكن المستهلك الصارم والمخطط المغلق قد يجعلان الإضافة غير متوافقة. راجع المحلل الفعلي لا الشعارات. يوفر OpenAPI لغة وصف بإصدار، وتفحص الأدوات القواعد التي تفهمها فقط. يستخدم المقتطف صياغة مخطط متوافقة مع OpenAPI 3.1 عمداً؛ وهو جزء مكوّن لا مستنداً كاملاً أو إثبات توافق مستهلك.
components:
schemas:
Reservation:
type: object
required: [id, seats, status]
properties:
id: { type: string, minLength: 1 }
seats: { type: integer, minimum: 1 }
status:
type: string
enum: [confirmed, cancelled]
ضعه في مستند OpenAPI كامل بمسارات واستجابات وتحقق بأدوات تدعم إصدار المواصفة المختار. تعداد الحالة مغلق عمداً، فتحتاج إضافة حالة مراجعة توافق المستهلكين.
تحقق من التفاعلات المنشورة لدى المزود
يثبت اختبار المستهلك مع محاكاة كيفية بناء الرسائل وتفسيرها وفق قواعدها، ويربط تحقق المزود التفاعلات بالتنفيذ. اجعل حالات المزود حتمية وانشر العقود من مراجعات معروفة بسير موثوق. يراعي قرار النشر المستهلكين الموجودين أو المدعومين فعلاً لا أحدث ملف فقط. Pact تنفيذ معروف للنهج ويحتاج وسيطه وسير التحقق إعداداً صريحاً. لا تعتبر استجابة JSON مكتوبة يدوياً عقداً متحققاً مدفوعاً بالمستهلك.
افصل التوافق عن الوظيفة
قد يثبت العقد إعادة الحقول والحالة المطلوبة دون صحة السعر أو التفويض أو السعة أو الأداء. احتفظ بتلك الفحوص في حزم وظيفة المزود والتكامل. اطلب في البوابة تحققاً حديثاً لهوية المزود المرشح ومجموعة العقود المناسبة. احفظ التفاعل الفاشل بتفاصيل محجوبة وحالة المزود المستخدمة. عند قدم الدليل أو غيابه أبقِ ادعاء التوافق مفتوحاً بدلاً من اعتبار اختيار عقود فارغ نجاحاً.
الأخطاء الشائعة وإصلاحها
تنجح اختبارات المزود وينكسر عميل قديم
- لماذا يحدث؟
- تحقق أحدث عقد مستهلك فقط.
- كيف تصلحه؟
- تحقق من تركيبات النشر المدعومة.
- كيف تتجنب تكراره؟
- تتبّع إصدارات المستهلك ومنشأ العقد.
تحمل استجابة مطابقة بيانات أعمال خاطئة
- لماذا يحدث؟
- استبدلت فحوص الشكل تحققات المعنى.
- كيف تصلحه؟
- أضف شروط نتائج وظيفية عند حد المزود.
- كيف تتجنب تكراره؟
- اذكر حدود كل ادعاء عقد.
تنحرف المحاكاة عن الخدمة الحقيقية
- لماذا يحدث؟
- تعدل البيانات دون تحقق المزود.
- كيف تصلحه؟
- تحقق من التفاعلات مقابل المزود المرشح.
- كيف تتجنب تكراره؟
- رقّم حزم العقود وراجعها كالمصدر.
اختبر فهمك
1. يضيف المزود قيمة حالة. لماذا قد تكسر المستهلك رغم كونها إضافة؟
اعرض الحل المشروح
قد يحصر العميل الحالات المعروفة أو يفحص تعداداً مغلقاً. افحص المحلل والعقد الفعليين. خطط انتقالاً متوافقاً أو تحديثاً وتحقق من فترة التعايش بدلاً من إعلان أمان كل إضافة.
2. يفحص اختبار API فقط response.ok(). قوّه لحجز مرفوض.
اعرض الحل المشروح
افحص حالة الرفض ورمز الخطأ الموثقين ثم ثبات السعة والحجوزات في بيانات مملوكة. يجب أن يفشل إذا أعاد الخادم رسالة خطأ مع استهلاك مقعد.
أهم ما تعلمته
- تحتاج صحة المخطط والتوافق والأعمال أدلة مختلفة.
- تخص العقود تركيبات مستهلك ومزود معروفة.
- تفيد المحاكاة ضمن استراتيجية تحقق صريحة.