استراتيجيات إصدار API

لماذا أحتاج إلى نسخ ؟

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

المبادئ الأساسية

1. مادة مضافة أولاً: مجالات/أساليب/أحداث اختيارية جديدة - حسنًا ؛ الحذف وتغييرات المعنى - كبيرة.
2. MGC (عقد الضمان الأدنى) مستقر ؛ الإثراء - من خلال القدرات/' ؟ تشمل = '.
3. القارئ المتسامح: يتجاهل العملاء المجالات غير المعروفة وينجو بشكل صحيح من امتدادات enum.
4. الإصدار الدلالي: 'MAJOR. قاصر. PATCH 'للقطع الأثرية و SDKs والأحداث.
5. أتمتة: مخطط diff، بطانات، واختبارات CDC تمنع تغييرات كسر.

مكان تخزين النسخة (ميكانيكا العنوان)

REST/HTTP

إصدار URI: '/v1/أوامر '→ سهل التوجيه ومريح في البوابات. ناقص - «يحجب» تطور الأفكار.
Media/Header: 'Application: application/vnd. مثال على ذلك. أوامر. v1 + json '- التحكم الدقيق في الشكل ؛ يصعب فضحها.
نسخة الاستفسار: '؟ api-version = 1 '- مناسب لـ A/B، ولكن من السهل خسارته في المخابئ/السجلات.
التوصية: URI للخطوط الرئيسية + أعلام الميزة/القدرة ونفي المحتوى للتمديدات الطفيفة.

gRPC/Protobuf

الحزم/الخدمات: 'مدفوعات الطرود. v1; PaymentsV1 الخدمات ؛ - خطوط صريحة.
ترقيم العلامات لم يتغير ؛ لا يمكن إعادة استخدام العلامات المحذوفة.
مجالات جديدة - 'اختياري' ؛ كسر → الجديدة '.v2'.

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

مخطط بدون تخصصات صريحة في عنوان URL. التطور من خلال نوافذ @ المهجورة والهجرة ؛ التخصص «الحقيقي» هو مخطط جديد لنقطة النهاية.
تعقيد/عمق التحكم هو جزء من العقد.

الحدث مدفوع (كافكا/ناتس/بولسار)

اسم الحدث: 'الدفع. المأذون به. v1 'هو الإصدار في النوع.
سجل المخطط (Avro/JSON Schema/Protobuf) مع نمط التوافق (BACKWARD/FORWARD/FULL).
Major → dual-emit 'v1' و 'v2' للفترة الانتقالية.

نموذج التنقيح وسياسة التغيير

الإصدار الدلالي

التغييرات الرئيسية - كسر التغييرات: حذف/إعادة تسمية الحقول، تغيير مفاتيح العضوية، معنى مختلف للحالات، تشديد التحقق من الصحة.
MINOR - إضافة: حقول/نقاط نهاية/أحداث اختيارية جديدة، قيم جديدة مع قارئ متسامح.
التصحيح - الإصلاحات دون تغيير العقد والدلالات.

الاستنكار وغروب الشمس

مارك عفا عليه الزمن («مستنكر: صحيح»، «@ deprecated»)، نشر تاريخ غروب الشمس، البديل ودليل الهجرة.
في HTTP - Headers' Sunset'، «Deprecation» ؛ في الأحداث - تفجير منفصل. إشعار ".
استخدام القياس عن بعد لتقرير ما إذا كان سيتم إزالته.

استراتيجيات التحويل حسب الأسلوب

راحة

الخطوط الرئيسية على/v1 ،/v2.
MINOR: تمديد المخطط، '؟ الحقول = '،' ؟ تشمل = '؛ تمديدات آمنة.
ETag/If-Match and idemputent POST لاتساق عدم الكسر.
الأخطاء - تنسيق مستقر («نوع»، «رمز»، «تتبع _ معرف»).

gRPC

تقديم خدمات/طرق جديدة للكسر: 'PaymentsV2. القبض '.
حالات الخطأ ودلالات الموعد النهائي هي جزء من العقد ؛ تغيير → طريقة/خدمة جديدة.
البث: وافق على أمر الرسالة ولا تغيره إلى ثانوي.

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

تضاف الحقول والأنواع بحرية ؛ الحذف - عبر '@ disprecated' + نافذة الهجرة ؛ إعادة تصميم كبيرة → مخطط جديد ('/graphql-v2 ').
الاستبطان والأوصاف - ضروري لهجرات العملاء.

الأحداث

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

أعلام التفاوض والقدرات

القدرات: يرسل العميل 'X-Factures: risk_score,price_v2'; يستجيب الخادم بعرض ممتد.
تفضيل (HTTP) والتلميحات للاستجابات الجزئية.
في المقابس/التدفقات - رسالة مصافحة مع قائمة بالإضافات المدعومة.

إطلاق إصدارات رئيسية دون ألم

1. RFC/ADR: لماذا هناك حاجة كبيرة، ما هي الفواصل، مصفوفة المخاطر.
2. ثنائي التشغيل: إطلاق مواز لـ «v1» و «v2» (نشر الحدث المزدوج، مسارين للبوابة، انعكاس حركة المرور).
3. محولات الهجرة: وكلاء/مترجمون «v1↔v2» للعملاء الكبار.
4. الكناري: حسب مجموعة العملاء/الموضوع/العلامة في البوابة.
5. خطة الغروب: التواريخ، الاتصالات، المدرجات، بيانات الاختبار، مراقبة الاستخدام.

أدوار المنصات والبنية التحتية

بوابة واجهة برمجة التطبيقات/شبكة الخدمة: التوجيه حسب الإصدار والرؤوس والمسارات ؛ الحد الأقصى للمعدل и auth لكل نسخة.
Schema Registry & Catalog: Source of Truth for Specs/Schemes with Diffuse History (باللغة الإنجليزية).
CI/CD: линтеры (Spectral، Buf)، schema-diff (OpenAPI-diff، Buf breaking)، CDC (Pact).
ملاحظة: ينبغي إدراج النسخة في السجلات/المسارات/المقاييس.

اختبار الإصدار

Schema-diff in PR: كسر الكتلة.
العقود التي يحركها المستهلك: يتم اختبار المزود مقابل عقود المستهلك الحقيقية.
العينات الذهبية: الردود المرجعية على الإصدارات.
E2E canary: مقارنة p95/p99، الأخطاء والوقت بين الإصدارات.
إعادة تشغيل الأحداث: يتم إعادة تجميع التوقعات إلى v2 مع عدم وجود تناقضات.

نقل البيانات وقواعد البيانات

بالنسبة لـ REST/gRPC: يتم تنسيق عمليات نقل قاعدة البيانات عن طريق التوسيع والعقد (أضف عمودًا → ابدأ الكتابة → تبديل القراءة → حذف القديم).
للأحداث: هجرة مزدوجة الانبعاثات والمستهلكين ؛ في بعض الأحيان - إعادة تسجيل التوقعات الجديدة.
لا تحدث «انفجارات كبيرة» - مقسمة إلى خطوات مع التراجع.

العلاقة الأمنية

النطاقات لكل إصدار: نطاقات/أدوار OIDC الفردية لـ v1/v2.
أسرار/ادعاءات الرمز هي جزء من العقد ؛ تغييرها = كبير.
PII/PCI - لا توسع الحمولة دون داع ؛ مجالات جديدة - مع حد أدنى من الامتيازات.

Antipatterns

Swagger-wash: تحديث المواصفات، الخادم ليس (أو العكس).
إعادة استخدام علامات protobuf هو فساد هادئ للبيانات.
تغيير معاني enum بدون تخصص.
Global '/v2 '«من أجل مستحضرات التجميل»: نسخة بدون حقيقة كسر.
نسيت مقاييس غروب الشمس/الاستخدام: من المستحيل إزالة الإصدار القديم بأمان.
موضوع واحد شائع لمختلف التخصصات: مزيج من الطلبات والمفاتيح.

القائمة المرجعية السابقة للإفراج

• التغييرات مضافة أو يتم إعداد خط رئيسي منفصل.
• البياضات و schema-diff خضراء (الكسر لم يزحف).
• تحديث SDK/أمثلة/وثائق، حواشي التوافق.
• تمكين القارئ المتسامح من العملاء ؛ تم اختبار enum-black.
• بالنسبة للخطة الرئيسية - ذات التشغيل المزدوج، والمحولات، والكناري، وتواريخ غروب الشمس، والبريد.
• تحتوي المقاييس/السجلات/المسارات على نسخة وتجزئة بواسطتها.
• هناك حامل ومجموعات ذهبية لمقارنة v1↔v2.
• بالنسبة للأحداث، يكون سجل المخطط في الوضع الخلفي/الكامل، ومفاتيح التقسيم لم تتغير.

عينة القوالب

REST (URI + التفاوض)

الطريق: '/api/v2/orders/{ id} '

Заголовок: "تفضل: تضمين = عناصر، عميل"، "إكس إمكانيات: risk_score'

الاستنكار: "غروب الشمس: 2026-06-30"، "الرابط: ؛ rel = "

Protobuf/gRPC

proto package payments. v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

الأحداث

الدفع. تم القبض عليه. v2 '(الأساسية) و' الدفع. إثراء. v2 '(التفاصيل).
بالنسبة للفترة الانتقالية، يذهب المنتج «v1» و «v2».

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

متى بالضبط مطلوب «/v2 »؟

عندما تتغير الثوابت/الدلالات، تتم إزالة الحقول/الطرق، وتغير شكل المعرفات، ومفتاح التقسيم، و SLA/التوقيت بحيث ينكسر العملاء.

هل يمكنك العيش بدون نسخة صريحة في REST ؟

للأنظمة الصغيرة فقط. بالنسبة للتكامل الخارجي، فإن الخطوط الرئيسية الصريحة أفضل.

كم من الوقت للاحتفاظ بالنسخة القديمة ؟

يعتمد على النظام البيئي. بالنسبة للشركاء الخارجيين، عادة 6-12 شهرًا مع الإخطار المبكر والكناري.

كيف يختلف إصدار الحدث عن API ؟

الأحداث - المرفقة فقط ؛ دلالات جديدة = نوع جديد «.v2» ومزدوج الانبعاث. مفتاح التقسيم هو جزء من العقد.

المجموع

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