إصدار واجهة برمجة التطبيقات (API) والتوافق مع الإصدارات السابقة: العقود التي لا تؤدي إلى كسر العملاء
إستراتيجيات إصدار عنوان URL/الرأس، وتغييرات المخطط الآمن، وسياسة الإيقاف لواجهات برمجة تطبيقات المنتج العامة والداخلية.
علي مرتضوي
مؤسس بارادايس كود
التوافق هو ميزة منتج، وليس تفاصيل تقنية
كل حقل تمت إزالته أو تغيير في المعنى يكسر شخصًا لا يمكنك رؤيته: تطبيق جوال قديم، أو برنامج نصي للعميل، أو تكامل شريك. الإصدار هو وعد محدد زمنيًا بشأن التغيير. وبدون هذا الوعد، فإن سرعة الميزة تؤدي إلى فقدان الثقة في واجهة برمجة التطبيقات (API).
حدد أولاً ما إذا كانت واجهة برمجة التطبيقات (API) عامة أم داخلية. لا تزال واجهات برمجة التطبيقات الداخلية بحاجة إلى إصدارات، ولكن يمكن أن تكون دورات الإيقاف أقصر.
مكان وجود الإصدار: المسار أو الرأس أو نوع الوسائط
تعد إصدارات المسار (`/v1/...`) صريحة وسهلة للبوابات والسجلات. تبدو الرؤوس أكثر نظافة في عناوين URI ولكنها تعقد عملية الاكتشاف والتخزين المؤقت. بالنسبة لمعظم منتجات B2B ومنتجات الهاتف المحمول، يعد إصدار المسار هو العقد الأكثر وضوحًا.
حجز الإصدارات الرئيسية للفواصل الحقيقية. يجب ألا تؤدي التغييرات الإضافية إلى إصدار الإصدار الثاني، وإلا ستحصل على نسخة متفجرة بدلاً من الانضباط.
التغييرات الآمنة مقابل التغييرات العاجلة
كلمة Safe تعني عادةً: حقول اختيارية جديدة، ونقاط نهاية جديدة، وتعدادات جديدة يتجاهلها العملاء غير المعروفين. الكسر يعني: إزالة الحقول، تغيير الأنواع، تغيير المعنى الافتراضي، جعل الحقل الاختياري السابق مطلوبًا.
لإعادة التسمية، قم بتشغيل فترة مزدوجة: الحقول القديمة والجديدة معًا، ثم تحذيرات الإهمال، ثم الإزالة في إصدار رئيسي.
عقود قابلة للاختبار والشيكات التي يحركها المستهلك
التحقق من صحة عقود OpenAPI/Protobuf في CI. اختبارات التوافق قبل الدمج تمنع الفواصل الصامتة. بالنسبة للفرق متعددة العملاء، تؤتي العقود التي يحركها المستهلك ثمارها مبكرًا.
احتفظ بأمثلة الاستجابة الحقيقية في المستندات، وليس المخططات فقط. يقوم العملاء بنسخ الأمثلة؛ الأمثلة القديمة تصبح أخطاء موزعة.
سياسة الإهمال مع التواريخ والمقاييس
يعد الإهمال بدون تاريخ وبدون مقاييس حركة المرور في الإصدار القديم بمثابة مسرح. أعلن عن تاريخ انتهاء الخدمة، وراقب الاستخدام، وتحدث إلى أصحاب العملاء.
بالنسبة للجوال، اقبل واقع المتجر: لا يقوم المستخدمون بالتحديث. في بعض الأحيان، يجب عليك الاحتفاظ بالإصدار القديم لفترة أطول أو إمكانية وضع علامة على الميزات من جانب الخادم.
إصدارات الخدمة والحدث الداخلية
تنطبق نفس المبادئ على الرسائل وgRPC: لا تحذف الحقول، واحتفظ بوضع التوافق، وتسامح مع المستهلكين غير المعروفين.
تسمح طبقة مكافحة الفساد عند الحدود للنماذج الداخلية بالتطور دون زعزعة العقد الخارجي.
الأسئلة الشائعة
هل يحتاج كل تغيير في واجهة المستخدم إلى إصدار جديد من واجهة برمجة التطبيقات؟
لا، فقط التغييرات التي تنتهك العقد. تضيف الميزات الجديدة عادةً حقولًا أو نقاط نهاية اختيارية.
كم عدد الإصدارات التي يجب أن نبقيها على قيد الحياة؟
أقل عدد ممكن — عادةً N وN-1. المزيد من تكاليف اختبار الانفجارات والأمن ما لم يكن لديك التزامات تعاقدية.
هل يزيل GraphQL الحاجة إلى الإصدار؟
لا؛ يغير الشكل. يظل الإهمال الميداني والتسامح مع العملاء القدامى ضروريين.
المعرفة والمقالات
تحتاج تطبيق هذه المفاهيم في منتجك؟
بارادايس كود معك من الاستشارة حتى التسليم الكامل.