توافق عقد API

لماذا توافق العقد

توافق العقد هو قدرة واجهة برمجة التطبيقات على التطور دون كسر عمليات التكامل الحالية. في النظم المتنامية، تتغير واجهات برمجة التطبيقات أكثر من كود العميل ؛ يسمح لك التوافق بإصدار الميزات بشكل متكرر، دون ترتيب «حركات كبيرة».

الفكرة الرئيسية: العقد أساسي، ويتم إجراء التغييرات وفقًا لقواعد التوافق ويتم فحصها تلقائيًا.

المفاهيم الأساسية

العقد - مواصفات الوصلة البينية الرسمية: الموارد/الأساليب/الأحداث، مخططات البيانات، رموز الأخطاء، الحدود، اتفاقيات البيئة المستدامة، المتطلبات الأمنية.
المزود - مالك واجهة برمجة التطبيقات. المستهلك - العميل/التكامل.

• إلى الوراء: يعمل المورد الجديد مع المستهلكين القدامى.
• إلى الأمام: يعمل المورد القديم مع مستهلكين جدد (عادة ما يحققه «القراء المتسامحون»).
• كامل: يتم ملاحظة كل من الخلف والأمام (الخيار الأقوى).
• الإضافة - أضف عناصر اختيارية دون كسر العناصر الموجودة.

سياسة التحديث

• MAJOR - كسر التغييرات (فقط عندما يتم إصدار خط API جديد: "/v2 "،" خدمة. v2 ').
• التغييرات الطفيفة في المواد المضافة (مجالات/طرق اختيارية جديدة).
• التصحيح - الإصلاحات دون تغيير العقد.
• سياسة الرفض: الإعلان عن العناصر القديمة، نافذة الدعم (غروب الشمس)، التحذيرات في الرؤوس/البيانات الوصفية، خطة الانسحاب.

تغييرات آمنة مقابل خطيرة

آمن (عادة ما يكون متوافقا مع الخلف)

أضف حقلًا اختياريًا إلى JSON/Protobuf/Avro.
أضف نقطة نهاية/طريقة/حدث جديد.
توسيع نطاق القيم الجديدة إذا كان المستهلكون متسامحين مع القيم غير المعروفة.
رفع الحدود (على سبيل المثال، «العناصر القصوى») دون تشديد الحد الأدنى.
إضافة غير قابلة للإلغاء مع التخلف عن السداد الصحيح.
تحرير الوصف/مثال النص.

خطير (يكسر التوافق)

إعادة تسمية/حذف الحقول، تغيير نوعها أو إلزامية.
تغير رمز الحالة/دلالات الخطأ (على سبيل المثال، كان «200»، وأصبح «204» أو «404»).
تغيير شكل المحددات (UUID → int).
تشديد التحقق (الحد الأدنى/الأنماط الأكثر صرامة) بدون نسخة.
تغيير الترتيب والبنية في تدفقات/أحداث gRPC.
إعادة استخدام أرقام العلامات في Protobuf للحقول الجديدة.

قابلية التشغيل البيني عن طريق أسلوب التفاعل

REST/HTTP + مخطط JSON

الإضافة: نضع علامة على المجالات الجديدة على أنها «اختيارية »/« غير قابلة للإلغاء».
القارئ المتسامح في العميل: تجاهل المجالات غير المعروفة ؛ لا تعتمد على النظام.
Versioning: major - on the tay ('/v2 ') or in the media type (' application/vnd. مثال على ذلك. v2 + json ').
ETag/If-Match: للحصول على تحديثات آمنة بدون سباق.
الأخطاء: تنسيق واحد («نوع»، «رمز»، «عنوان»، «تفاصيل»، «تتبع _ معرف»)، لا تغير قيمة «رمز» بدون تخصص.
التثبيت: يفضل تعويض المؤشرات ؛ أضف حقول «المؤشر التالي»، لا تغير معنى الحقول الموجودة.

gRPC/Protobuf

ترقيم العلامة لم يتغير. لا يمكن إعادة استخدام العلامات المحذوفة.
الحقول الجديدة «اختيارية »/« متكررة» مع افتراضات معقولة على الخادم.
لا تغير الطلب والرسائل الإلزامية في بث RPC.
أوضاع الخطأ مستقرة ('غير صالح _ ARGUMENT'، 'FAILL _ PRECONDITION'، إلخ) ؛ دلالات جديدة → نسخة جديدة من الطريقة/الخدمة.

الحدث مدفوع (كافكا/ناتس/بولسار) + مخطط أفرو/جسون

تسمية الأحداث: 'المجال. العمل. v {major} '.
والميادين الجديدة اختيارية ؛ عزل النواة والإثراء ('.
سجلات المخطط: قواعد التوافق (BACKWARD/FORWARD/FULL) بشأن الموضوع/الحدث.
امتداد enum صالح للقارئ المتسامح من جانب المستهلك.
تغيير مفتاح التقسيم/الطلب للمجموع = كسر التغييرات.

الرسم البياني QL

إضافة الحقول/الأنواع آمنة ؛ حذف/إعادة تسمية - فقط من خلال @ disprecated ونافذة الهجرة.
لا تغير الأنواع/غير قابلة للإلغاء بدون التخصص.
تعقيد/عمق التحكم - الحدود جزء من العقد.

أنماط التطور المستدامة

مادة مضافة أولاً: توسع دون كسر.
التفاوض على القدرات: يفيد العملاء بأنهم يدعمون (الرؤوس/البارامترات/الاتفاقات)، ويعدل الخادم.
حدود العقد: إصلاح MGC (عقد الضمان الأدنى) وتمديدات منفصلة (نموذج الهرم العكسي).
التسامح افتراضيًا: يتجاهل العملاء القيم غير الضرورية ويتعاملون بشكل صحيح مع القيم غير المعروفة (الاحتياطية).
ثنائي الكتابة/ثنائي الانبعاث: للتغييرات الرئيسية، إطلاق 'v1' و 'v2' بالتوازي لفترة من الوقت.
رؤوس/أحداث غروب الشمس: أخطر مسبقًا عند إزالة الإصدارات.

الحوكمة والأتمتة

• OpenAPI/Spectral: التسمية، الترويج، رموز الخطأ، تنسيقات الحقل.
• Buf/Protobuf: عدم السماح بإعادة استخدام العلامات، ترميز الحزمة.
• AsyncAPI/Schema Registry: توافق المخطط على مستوى CI.
• Centralization Catalog (SSOT): Centralized schema/version registration with diffuse history.
• نقابة API: نقابة/لجنة تعتمد القواعد والنماذج وتغييرات المراجعة.
• إدارة التغيير: RFC/ADR، ملاحظات الإصدار، أدلة الهجرة.

اختبار التوافق

Schema-diff in CI: block breakes (OpenAPI-diff، Buf breaking، SR compatibility).
العقود التي يحركها المستهلك (CDC): الميثاق/المماثل - المورد مقابل العقود الخاصة بالمستهلك.
العينات الذهبية: الاستفسارات المرجعية/الردود والأحداث المتعلقة بالانحدار.
E2E كناري: طرح حصة حركة المرور/مجموعات المستهلكين الفردية.
الفوضى/زمن الكمون: Timeout/Retray check - يعتبر تغيير زمن الكمون-SLO تغييرًا في العقد.

الهجرات والاستنكار

1. أعلن نقض: ضع علامة على العنصر، وحدد مصطلح غروب الشمس والبديل.
2. الحفاظ على فترة التوافق: مزدوجة الكتابة/مزدوجة الانبعاث، جسور، محولات.

3. جمع القياس عن بعد: من يستخدم القديم أيضًا ؟

4. الاتصال: رسائل بريدية، ملاحظات إصدار، منصات اختبار.
5. الإزالة: بعد انتهاء صلاحية النافذة - الإزالة بإطلاق ثابت.

أمثلة على التغييرات

راحة

json
{ "id":"p1", "status":"authorized" }

json
{ "id":"p1", "status":"authorized", "risk_score": 0. 12 }

العملاء الذين يتجاهلون الحقول المجهولة لا ينكسرون.

بروتوبوف

proto message Payment {
string id = 1;
string status = 2; // don't change tag numbers optional double risk_score = 3; // additive
}

حدث

الدفع. المأذون به. v1 '(الأساسية) +' الدفع. إثراء. v1 '(الإثراء). يقرأ المستهلكون المسار الحرج النواة ولا يعتمدون على الإثراء.

Antipatterns

غسل التبجح: هناك مواصفات رسميًا، لكن سلوك الخدمة يتعارض معها.
الكسر عن طريق التخفي: تغيير النوع/الحالة/التنسيق بدون إصدار جديد ونافذة الهجرة.
أحداث مركز السيطرة على الأمراض كعقد عام: مخططات DB المسربة، استحالة التطور.
العميل الصلب: قطرات في مجالات/قيم غير معروفة ؛ عدم وجود قارئ متسامح.
إعادة استخدام علامات protobuf: فساد البيانات الهادئ.
الكمون باعتباره «غير عقد»: تم إطالة p95 بشكل غير متوقع - ينهار المستهلكون في المهلات.

قائمة مرجعية للتوافق (قبل الدمج)

• التغييرات مضافة (أو نسخة رئيسية معدة).
• تم تمرير فحوصات البطانات/diff، وقواعد التوافق خضراء.
• الأخطاء/الرموز/الأوضاع لم تغير الدلالات.
• امتد Enum دون حظر القيم القديمة ؛ العملاء - متسامحون.
• لم تتغير حدود MGC.
• عينات/وثائق مستكملة/SDK.
• بالنسبة للخطة الرئيسية - خطة الكتابة المزدوجة/مزدوجة الانبعاث، تاريخ الغروب، خطة الاتصال.
• الاختبارات CDC/Golden/E2E اجتازت.

الأسئلة الشائعة

كيف يختلف الخلف عن التوافق الأمامي ؟

إلى الوراء - الخوادم الجديدة لا تكسر العملاء القدامى. إلى الأمام - لا يكسر العملاء الجدد الخوادم القديمة (عبر القارئ المتسامح والتخلف عن السداد الأنيق).

متى تفعل «/v2 »؟

عندما تتغير الثوابت/الدلالات، يتم حذف الحقول/الأساليب، مطلوب نموذج أمان جديد - من الأسهل والأكثر صدقًا بدء خط جديد.

هل يمكنك العيش بدون Schema Registry/linters ؟

من الناحية النظرية - نعم، عمليًا - هذه انحدارات متكررة وانهيارات «مخفية». الأتمتة تؤتي ثمارها.

يمكن تمديد Enum ؟

نعم، إذا تعامل العملاء بشكل صحيح مع قيم غير معروفة (احتياطي/تجاهل). خلاف ذلك - الرائد.

المجموع

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