استراتيجيات إصدار 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 - لا توسع الحمولة دون داع ؛ مجالات جديدة - مع حد أدنى من الامتيازات.

الأنماط المضادة

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» ومزدوج الانبعاث. مفتاح التقسيم هو جزء من العقد.

النتيجة

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