خريطة تبين أثر إيقاف إصدار API على التطبيقات المرتبطة به: مشاريع تخرج هندسة البرمجيات

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

فرّق بين إشارة وتاريخ قرار

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

تسمح OpenAPI Specification 3.1.1 بتعليم عملية أو عنصر بأنه deprecated في وصف العقد، ولا تضع وحدها خطة إزالته. يحدد RFC 8594 حقل HTTP يسمى Sunset للإشارة إلى موعد قد يصبح فيه المورد غير متاح. وضح الفرق داخل التطبيق: خاصية العقد مصدرها ملف OpenAPI، وحقل الاستجابة يمكن أن يظهر من خادم اختباري إذا نفذه. لا يفترض النظام أن إحدى الإشارتين موجودة لمجرد وجود الأخرى.

أنشئ سجلاً للمستهلكين المعروفين

أدخل مستهلكاً اصطناعياً لكل تطبيق أو لوحة داخلية: الاسم الوظيفي، مسارات API المستخدمة، الإصدار الحالي، جهة صيانة داخلية، حالة النقل، رابط اختبار العقد، وآخر تاريخ مراجعة. تجنب أسماء طلاب وأسرار أو معرّفات مستخدمين. افتح ملف OpenAPI واستخرج الطريقة والمسار والوصف وعلامة deprecated، ثم اربطها بالمستهلكين التي أدخلها الفريق. إذا لم يكن المستهلك معروفاً، اجعل حالته «غير موثق» ولا تعرض عبارة «لا أحد يستخدمه».

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

مثال مسار بحث قديم ونسخة بديلة

في سيناريو خيالي يقدم المسار /v1/search بحثاً باسم المساق، ثم يضيف الإصدار التالي مرشح فصل دراسي في /v2/search. ملف العقد يصف الأول بأنه deprecated، والمستهلكون هم موقع كتالوج وتطبيق هاتف وواجهة عرض. يثبت اختبار عقد محلي أن الموقع قرأ v2؛ الهاتف لم يرفق نتيجة بعد؛ وواجهة العرض لا تستخدم عملية البحث. تعرض الخريطة ثلاث حالات وخطوة مطلوبة لكل منها. لا تؤكد أن واجهة العرض جاهزة للإزالة حتى يراجع صاحبها سبب غياب الاستخدام.

يمكن لمحاكي محلي أن يرسل response يحمل Sunset إلى مثال عميل، فيعرض تاريخاً ويفتح قائمة ترحيل. هذا اختبار لقراءة حقل response، لا دليل على أن الخادم الحقيقي يرسله أو أن التاريخ ملزم. لا تغير الأداة routing أو تعطل v1؛ زر «محاكاة الإزالة» يعرض ما قد يبقى غير مغطى فقط. المثال اصطناعي ولا يرتبط بخدمة مستخدمة في الجامعة. احتفظ بلقطة للعقد قبل وبعد النقل كي يراجع الفريق التغيير.

اربط الخريطة بأدلة اختبار

لكل مستهلك حالة اختبار تثبت القراءة أو الكتابة المقصودة، وحالة تعلن ما الذي تغير في العقد. أرفق رابط تقرير CI أو mock response محلياً، وسجل إصدار التطبيق المرتبط به. قد ينجح اختبار واحد بينما تفشل مهمة لم يغطها؛ لذلك اسم الاختبار والنطاق مهمان. إذا لم توجد أدلة، اظهر الحالة «غير مثبت» بدلاً من اعتبار tick checkbox انتقالاً. لا ترفع شيفرة أو tokens إلى خدمة طرف ثالث عند إنشاء التقرير.

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

اختبر parse ووقتاً لم يحن

جهز عقداً فيه عملية نشطة وأخرى deprecated، وعمليتين غير مربوطتين بمستهلك، ثم response مع Sunset وآخر بدونه. اختبر ملف OpenAPI غير صالح ونسخة لا يدعمها parser. يجب ألا تتحول حالة «معلن التقاعد» إلى «محذوف» بمجرد تجاوز تاريخ اليوم؛ تطلب قراراً بشرياً وتوضيحاً من خدمة المالك. اختبر المنطقة الزمنية والتاريخ في العرض، وتأكد أن deprecated: true يقرأ على العملية الصحيحة ولا يلتبس بتعليق description.

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

اعرض الخريطة ولا تنفذ الإيقاف

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

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