الحقل القديم قد يعيش أطول من الخادم الجديد
يبدو حذف حقل قديم من استجابة JSON تغييرًا بسيطًا في المستودع، لكنه قد يوقف تطبيقًا لا يزال يستخدم نسخة قديمة من المكتبة أو تكاملًا لم يُحدّث منذ أشهر. المشكلة ليست في رقم الإصدار وحده؛ إنها معرفة من يستهلك الحقل، وهل يستطيع الانتقال، ومتى يمكن إزالته من دون قطع الخدمة. هذا الدليل يركز على دورة حياة حقل محدد، وإشارات HTTP الرسمية، والقياس الميداني للهجرة. أما المبادئ العامة لتصميم REST API فموثقة في مقالات أخرى؛ هنا سنبني خطة تنفيذ قابلة للاختبار تبدأ من اكتشاف الاستخدام وتنتهي بقرار إيقاف قابل للتراجع.
ابدأ بعقد الحقل لا باسم الإصدار
اكتب تعريفًا دقيقًا للحقل المرشح للإيقاف: اسمه، نوعه، هل يقبل null، هل يظهر في جميع الاستجابات، وهل يعتمد عليه العميل في قرار تجاري. قد يبدو تغيير الاسم من total إلى amount تجميليًا، لكنه يكسر قارئ JSON يعتمد على المفتاح القديم. لا تفترض أن جعل الحقل اختياريًا يكفي إذا كانت تطبيقات سابقة تعاملت معه كقيمة إلزامية. اجمع أمثلة استجابات من الإنتاج بعد إزالة البيانات الحساسة، وقارنها مع OpenAPI والاختبارات التعاقدية. إذا كان الحقل يُستخدم للعرض فقط فالمخاطر تختلف عن حقل يحسب الضريبة أو حالة الدفع.
التمييز بين التوقف عن التوصية والتوقف عن الخدمة
Deprecation تعني أن الاعتماد الجديد على المورد غير مستحسن وأن الهجرة مطلوبة، لكنها لا تعني بالضرورة تغير السلوك اليوم. Sunset يعلن توقع توقف المورد أو الإصدار عن الاستجابة في تاريخ محدد. يصف RFC 9745 ترويسة Deprecation وعلاقة link للوثائق، بينما يصف RFC 8594 ترويسة Sunset. هذه الإشارات تتعلق أساسًا بموارد HTTP، وليس من الدقة الادعاء بأن إرسال ترويسة واحدة يعلن آليًا إيقاف حقل JSON فردي لكل العملاء. يجب توثيق نطاق الإشارة: مورد، مجموعة موارد، إصدار كامل، أو حقل محدد موضح في صفحة الهجرة.
كيف تكتب إشعارًا يستطيع العميل فهمه؟
اجعل صفحة الهجرة تجيب عن خمسة أسئلة: ما الحقل القديم، وما البديل، وهل توجد فروق دلالية، وما آخر موعد موصى به للتحديث، وكيف يختبر العميل جاهزيته. لا يكفي إرسال رسالة بريد إلى صاحب حساب قديم؛ ربما لا يصل إلى الفريق المسؤول عن التكامل. أضف ترويسة أو رابط توثيق واضحًا في الاستجابة عندما يسمح عقد API، وانشر سجل تغييرات مرتبًا زمنيًا، وأرسل إشعارًا للقنوات الرسمية للعملاء النشطين. لا تستخدم نصًا مخيفًا مثل سيتوقف فورًا إذا كانت الخطة تسمح بمرحلة توافق؛ الدقة تقلل أخطاء الترحيل.
مرحلة التوافق المزدوج
في كثير من الحالات يكون النهج الأقل كسرًا هو إرجاع الحقل القديم والجديد لفترة انتقالية مع دلالة متطابقة، مع توثيق أي اختلاف في الوحدات أو المنطقة الزمنية أو التقريب. لكن لا تنس أن نسخ قيمة غير صحيحة إلى اسمين لا يحل خطأها. عند تغيير وحدة القياس، أضف اسمًا صريحًا للوحدة واختبر الحدود والقيم الكبيرة والسالبة. ضع سياسة إذا تعارضت القيم في طلبات الكتابة: هل تقبل القديم، أم الجديد، أم ترفض وجودهما معًا؟ لا تترك القرار لآخر middleware يصادف الطلب. صمم مصفوفة توافق لكل عميل مع عينات معروفة.
رصد العملاء دون جمع بيانات أكثر من اللازم
قياس استهلاك حقل داخل استجابة ليس مباشرًا؛ الخادم يعرف أنه أرسله لكنه لا يعرف بالضرورة إن كان تطبيق العميل قرأه. يمكن استخدام نسخ API مختلفة أو ترويسات إصدار يرسلها العميل أو Telemetry طوعية في SDK، لكن لكل مؤشر حدودًا. لا تعرض تقريرًا يدعي أن صفر طلبات إلى endpoint القديم يعني أن جميع العملاء توقفوا عن استخدام الحقل إذا كان الحقل داخل استجابة مشتركة. صنّف المستهلكين بحسب تطبيقاتهم وتواريخ آخر نشاطهم، واجمع مؤشرات مجمعة تحترم الخصوصية، وتواصل مع العملاء ذوي التأثير المرتفع عند الحاجة.
نسخة جديدة أم تعديل داخل النسخة؟
تغيير حقل اختياري في استجابة قد يكون أقل كسرًا من تغيير نوع حقل موجود من رقم إلى نص. بعض الفرق تستخدم إصدارًا في المسار مثل /v2، وأخرى في ترويسة أو عقد زمني. لا توجد طريقة واحدة تضمن التوافق؛ الأهم ثبات القاعدة وإعلانها. عند إزالة حقل تعتمد عليه تطبيقات قديمة، قد تحتاج إصدارًا رئيسيًا جديدًا أو طبقة توافق بدل تعديل صامت في الإصدار نفسه. حدد تكلفة تشغيل النسختين وتاريخ التقاعد، واختبر أداء مسار التوافق. لا تضاعف الإصدارات لكل تعديل صغير إذا كان يمكن تحقيق انتقال آمن موثق.
اختبار العقود قبل طرح التغيير
ابنِ اختبارات Consumer-Driven Contracts عندما تكون لديك تطبيقات عميلة معروفة، أو اختبارات تكامل تمثل إصدارات SDK المستخدمة. اختبر حالة الحقل المفقود، والقيمة null، والنوع القديم، والنوع الجديد، والحدود الرقمية. افحص أيضًا الترتيب غير المضمون لمفاتيح JSON، لأن الاعتماد على ترتيبها خطأ مستقل. عند وجود تطبيق جوال قديم لا يمكن تحديثه فورًا، نفذ اختبارًا على نسخة واقعية من التطبيق بدل افتراض أن آخر SDK يمثل جميع المستخدمين. اربط نتيجة الاختبار برقم البناء والعقد الذي فُحص، ولا تعتبر مرور الاختبارات الداخلية إثباتًا لسلامة كل عميل خارجي.
متى تستخدم Deprecation و Sunset؟
يمكن إرسال Deprecation عندما يصبح المورد قديمًا، وربطه بوثيقة تشرح الهجرة. أما Sunset فيناسب إعلان موعد متوقع لانتهاء إتاحة المورد، مع صيغة تاريخ HTTP موثقة. يحذر RFC 9745 من أن تاريخ Sunset لا ينبغي أن يسبق تاريخ Deprecation. وإذا كان التغيير خاصًا بحقل داخل JSON، فاشرح في الوثائق صراحة أن الإشارة مرتبطة بنطاق أوسع من مورد واحد أو استخدم آلية إعلانات مكملة. لا تخلط بين هاتين الترويستين وبين Cache-Control أو Retry-After؛ لكل منها غرض مختلف، ولن يفسر العميل تلقائيًا موعد التوقف دون دعم صريح.
خطة طرح تدريجية مع خيار رجوع
قسّم النشر إلى مراقبة ثم توافق مزدوج ثم تحذير ثم إزالة بعد تحقق كافٍ. قبل مرحلة الإزالة جهز مفتاحًا تشغيليًا يسمح بإعادة الحقل إذا ظهرت أعطال غير متوقعة، وحدد من يملك صلاحية اتخاذ القرار. لا تجعل الرجوع يعيد شكلًا قديمًا مع بيانات مختلفة غير موثقة. جرّب إزالة الحقل في بيئة staging على عملاء ممثلين، ثم راقب أخطاء التحليل والتذاكر ومعدلات الطلبات الفاشلة. احتفظ بتاريخ واضح للخطوة التالية ولا تقدم التواريخ التقديرية على أنها التزام قطعي ما لم يعتمدها الفريق. المهم تقليل المفاجآت لا مجرد الالتزام بموعد.
كيف تتعامل مع عملاء لا يمكن تحديثهم؟
قد يكون لدى مؤسسة عميل مضمن في جهاز أو تطبيق جوال متوقف عن الصيانة. افصل الحالات: عميل نشط لكنه متأخر، عميل لا يستخدم المورد، وعميل مجهول لا توجد له إشارة إصدار. لكل فئة خطة مختلفة؛ يمكن توفير طبقة توافق محددة المدة، أو بديل عبر gateway، أو عقد دعم خاص إذا كان ذلك مناسبًا. لكن لا تجعل الاستثناءات غير المحددة زمنيًا تمنع التطوير إلى الأبد. وثق تكلفة كل استثناء وأثره على الأداء والأمان، وحدد مالك القرار. لا تفترض أن كل عميل متأخر يحتاج مهلة واحدة؛ قيّم الاعتماد الفعلي والمخاطر.
جدول القرار والقياس
قارن بين أربعة خيارات: إبقاء الحقل كما هو، إعادته مع بديل جديد، إصدار جديد، وإزالته. قيّم لكل خيار عدد العملاء المتأثرين، تكلفة الصيانة، إمكانية التراجع، وحجم التغيير في العقد. عندما تكون بيانات الاستهلاك ناقصة، سجلها بصفتها مجهولة بدل استنتاج عدم الاستخدام. حدد مؤشرات متابعة مثل نسبة الطلبات ذات إصدار SDK معروف، وعدد أخطاء parsing، وتذاكر الدعم المرتبطة بالحقل، ونسبة العملاء الذين أكدوا الاختبار. هذه المقاييس ليست بديلاً عن تجربة العميل، لكنها تمنح الفريق إشارات عملية لتأجيل أو إكمال الخطوة.
مقارنة استراتيجيات إيقاف حقل REST
| الإبقاء | أعلى توافق قصير الأجل | مخاطر محدودة |
| توافق مزدوج | مرحلة انتقالية | قياس المستهلكين |
| إصدار جديد | عقد مستقل | تغيير كاسر |
| الإزالة | قد تكسر عملاء قدامى | تحقق وخطة تراجع |
قائمة تنفيذ لمدير المنتج والمطور
قبل اعتماد الإزالة، تحقق من توثيق الحقل والبديل، ومن صحة التواريخ، ومن إرسال إشارات Deprecation عند ملاءمتها، ومن وجود صفحة هجرة وأمثلة طلبات واستجابات، ومن تغطية اختبارات العقود والنسخ القديمة. تأكد من أن لوحة المراقبة لا تخلط إرسال الحقل باستهلاكه، ومن وجود مالك لقرار Sunset وخطة تراجع. جرّب إعادة تفعيل الحقل في بيئة اختبار واحسب زمن الاستعادة. عند اكتمال الانتقال، احتفظ بسجل قرار يشرح لماذا أزيل الحقل وما الذي تحقق بالفعل. لا تدّع عدم وجود عملاء متأثرين من دون أدلة كافية.
المراجع وروابط المتابعة
النص المعياري لترويسة Deprecation في RFC 9745: https://www.rfc-editor.org/rfc/rfc9745.html ، وترويسة Sunset في RFC 8594: https://www.rfc-editor.org/rfc/rfc8594.html ، ودلالات استجابات HTTP في RFC 9110: https://www.rfc-editor.org/rfc/rfc9110.html . وعلى إيجي تاج راجع المقال الأشمل عن تغيير واجهات API دون كسر العملاء: https://egytag.com/ar/articles/%D8%AA%D8%BA%D9%8A%D9%8A%D8%B1-%D9%88%D8%A7%D8%AC%D9%87%D8%A7%D8%AA-api-%D8%AF%D9%88%D9%86-%D9%83%D8%B3%D8%B1-%D8%A7%D9%84%D8%B9%D9%85%D9%84%D8%A7%D8%A1-%D8%AE%D8%B7%D8%A9-%D8%B9%D9%85%D9%84%D9%8A%D8%A9-%D9%84%D8%A5%D8%AF%D8%A7%D8%B1%D8%A9-%D8%A7%D9%84%D8%AA%D9%88%D8%A7%D9%81%D9%82-%D9%88%D8%A7%D9%84%D8%A5%D8%B5%D8%AF%D8%A7%D8%B1%D8%A7%D8%AA . النصوص المعيارية تصف سلوك الترويسات ولا تضمن التزام كل عميل بها؛ اختبر التكاملات الفعلية.
شارك في تقييم ونقاش المقال
رأيك يضيف قيمة للمقال ويساعدنا على تحسين المحتوى والنقاش حوله.
النقاش
جارٍ تحميل التعليقات…