إصدار API وتوافق العقد

TL; د

التوافق هو الانضباط وليس الحظ. احتفظ بسياسة إصدار واضحة (SemVer)، وتغيير الرياضيات (ما «يكسر»، وما لا يفعل)، واختبارات العقد، وسجلات المخطط، وإجراءات الغروب. للمال والامتثال - REST/gRPC الصارم مع vN، لتجميعات واجهة المستخدم - الرسم البياني التطوري مع «@ deprecated». دائمًا: حركة مرور الكناري، والتوافق الخلفي ≥ ودورة إطلاق واحدة، وأدلة الهجرة، والقياس عن بعد الميداني.

1) المفاهيم والأهداف الأساسية

متوافق مع الخلف (BC): العملاء القدامى مناسبون للخادم الجديد.
متوافق مع الأمام (FC): العملاء الجدد مناسبون للخادم القديم (محدود).
توافق الأسلاك: لا ينكسر التنسيق الموجود على «السلك» (مهم بشكل خاص لـ gRPC/Protobuf).
SemVer: 'MAJOR. قاصر. PATCH '- كسر العقد → رفع MAJOR.

الهدف هو تقليل التغييرات التخريبية وتوفير نوافذ هجرة يمكن التنبؤ بها.

2) مصفوفة التغيير: ما يمكنك وما لا يمكنك فعله

3) سياسات لأنماط API مختلفة

3. 1 راحة

النسخة في URI ('/v1/... ') أو المجال (' api-v1. '). نسخة الرأس - للحالات الداخلية فقط.
أضف، لا تحذف: حقول جديدة - حسنًا، قديمة - ضع علامة على أنها «مستنكرة» في الرسم البياني واتركها لدورة واحدة على الأقل.
الحالات/الأخطاء: لا تغير الرموز وخطأ الهيكل. الرمز/الخطأ. رسالة/خطأ. التفاصيل ".
لم يتغير الفراغ: لا تحول «POST» الآمن مع «Idempotency-Key» إلى تحدٍ «مختلف سلوكيًا».

3. 2 gRPC/Protobuf

الأرقام الميدانية مقدسة: لا تعيد استخدام الأرقام المحذوفة، وعلامة «محفوظة».
إضافة حقول اختيارية/سحب جديدة ؛ «إلزامي صعب» - من خلال المصادقة، وليس «استفسار».
حزم الإصدار: 'المدفوعات. v1 '،' المدفوعات. v2 '.
توافق الخدمات: تسهيلات جديدة → طريقة جديدة ؛ نحن لا نغير سلوك القديم.

proto message Payout {
reserved 4 ;//field deleted, number reserved string id = 1;
string currency = 2;
int64 amount_minor = 3;
// v2: optional string comment = 5;
}

3. 3 رسم بياني QL

التطور بدون v2: إضافة حقول/أنواع ؛ الحذف - من خلال «@ disprecated (سبب)» مع إعلان النافذة.
الاستفسارات المستمرة: بالنسبة للعملاء العامين، استخدم قائمة بيضاء من الاستفسارات - من الأسهل التحكم في التوافق.
المستوى الميداني authZ والقياس عن بعد: اعرف الحقول التي تستخدم بالفعل قبل الحذف.

graphql type Payout {
id: ID!
amountMinor: Long!
currency: String!
comment: String @deprecated(reason: "Use note")
note: String
}

3. 4 عناوين ويب

النسخة في المسار ('/webhooks/v1/payments') وغلاف الحدث الثابت ('event _ id', 'type', 'ts',' data ').
إبقاء التوقيعات على حالها ؛ خوارزميات جديدة - كخيار بعلم.
الامتدادات - فقط من خلال بيانات الحقول الجديدة. "و" الرؤوس "- دون حذف القديمة.

4) واجهة برمجة التطبيقات البوابة وتوجيه الإصدار

التوجيه القائم على القواعد: حسب البادئة '/v1 '، بواسطة الترويسة' X-Api-Version '، حسب المجال.
الظل/الكناري: يعكس بعض حركة الإنتاج في الإصدار الجديد «في الظل»، قارن الإجابات.
السعر/الحصص لكل إصدار: يحمي العملاء الأكبر سنًا أثناء الهجرة.

• «غروب الشمس: <تاريخ RFC>» - تاريخ إغلاق الإصدار
• «الاستنكار: صحيح» - النسخة عفا عليها الزمن
• الرابط: ؛ rel = «الاستنكار» - في دليل التغيير/الهجرة

nginx location ~ ^/v2/ {
proxy_pass http://api_v2;
}
location ~ ^/v1/ {
add_header Deprecation "true";
add_header Sunset "Thu, 01 May 2026 00:00:00 GMT";
proxy_pass http://api_v1;
}

5) سجلات وعقود المخطط

OpenAPI/JSON Schema для REST; واصفات Protobuf для gRPC ؛ سجل SDL для الرسم البياني QL.
فحص CI: البطانات + «كسر التغييرات» في العلاقات العامة.
العقود التي يحركها المستهلك (CDC): اختبارات المستهلك (الميثاق/التناظري) - الحماية من فترات الراحة غير الواضحة.
Changelog: قابل للقراءة آليًا (على سبيل المثال، "CHANGELOG. md '+ ملاحظات الإصدار في السجل).

6) تطور الحقول: القواعد الأساسية

المعرف/المفاتيح: لا تغير الشكل (UUID↔int) بدون حقل جديد '_ v2' وفترة انتقالية.
الوقت/العملة: الاحتفاظ ISO-8601/epoch التوقيت العالمي المنسق والعملة amount_minor + ؛ لا تقيس (بنسات/سنتات).
Enum: أضف القيم - حسنًا ؛ لا تغير معنى القدامى بالنسبة لـ REST، أعط قيم السلسلة وليس الإيماءات.
التثبيت: معتمد على المؤشر أكثر استقرارا ؛ لا تغير دلالات المؤشر.

7) إجراء الاستنفاد و «غروب الشمس»

1. إعلان (T-90/60): changelog، إرسال بريد إلى الشركاء، عناوين "Deprecation/Sunset'.
2. الفترة المزدوجة: يعمل V1 و V2 بالتوازي ؛ V1 مزود بتحذيرات في الردود/السجلات.
3. القياس عن بعد للاستخدام: من يتصل بـ V1 ؟ نقاط الاتصال.
4. تجميد V1: فقط إصلاحات الأخطاء/لا توجد ميزة.
5. Sunset-410 ذهب أو صفحة كتلة تعليمات الهجرة.

8) الإطلاقات الخالية من الألم: استراتيجيات وضع

التوجيه الأزرق/الأخضر أو المرجح: 1-5-25-50-100٪ حركة المرور.
نافذة التوافق: 1-2 إصدارات طفيفة على الأقل، في كثير من الأحيان 6-12 شهرًا لواجهات برمجة التطبيقات الخارجية.
ميزة الأعلام لتشمل مجالات/فروع منطقية جديدة دون ترقية.
اقرأ/اكتب تقسيم: أضف أولاً دعمًا لقراءة مجال جديد، ثم ابدأ في كتابته.

9) اختبار التشغيل البيني (مجموعة التدريب)

اختبارات ذهبية للردود من الإصدارات القديمة.
اختبارات Diff للدوائر: لا كسر في CI.
يعمل إنتاج إعادة التشغيل على مراحل V2 (الظل).
النصوص الخلفية/الأمامية: عميل جديد على الخادم القديم والعكس صحيح (حيث يكون FC صالحًا).
الاختبارات التعاقدية للخطابات الشبكية: التحقق من التوقيع والشكل والوقت.

10) مقاييس عملية الإصدار ومسؤولياتها

٪ من العملاء في آخر MINOR (الهدف ≥ 80٪ قبل غروب الشمس).
أخطاء التوافق/عدم التوافر لكل إصدار (الهدف 0).
حصة المكالمات القديمة (تتناقص إلى غروب الشمس).
وقت هجرة العملاء (متوسط/ص 95).
دلتا الكمون/الانحدار بين الإصدارات (ليس أسوأ من الأساسي).

11) أمثلة على القطع الأثرية

yaml components:
schemas:
Payout:
type: object properties:
id: { type: string, format: uuid }
amount_minor: { type: integer }
currency: { type: string }
comment:
type: string deprecated: true description: "Use note"
note: { type: string }

proto syntax = "proto3";
package payouts. v1;
message Payout { reserved 5; string id=1; int64 amount_minor=2; string currency=3; }

graphql type Query { payout(id: ID!): Payout }

12) إصدار القنوات المجاورة

SDK/CLI: اعتماد إصدار SemVer + API، التوافق المنصوص عليه في README.
Events/streams (WS/Kafka): نسخة في 'ظرف. نسخة '؛ خصائص جديدة - اختيارية ؛ ديدوب واستئناف العمل نفس الشيء بين الإصدارات.
الإبلاغ/CSV: نسخة باسم الملف/الرأس ؛ إضافة أعمدة إلى اليمين لا تغيير الترتيب/الأنواع.

13) الحوكمة والأدوار

مالك العقد (مالك النطاق)، Steward API (القواعد والبياضات)، مدير الإصدار (Sunset/communications).
عملية RFC لكسر التغييرات: تبرير الأعمال، خطة الهجرة، القطع الأثرية، التواريخ.
دليل واجهة برمجة التطبيقات الموحد: حيث تكون المخططات والإصدارات وتقويم الغروب والاتصال مرئية.

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

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

15) إصدار قائمة التحقق من الإصدار الجديد

• مخطط محدث (OpenAPI/Protobuf/SDL)، تم تمرير البطانات وفحوصات الكسر.
• تمت إضافة اختبارات التكامل والعقد (CDC).
• دليل SDK/نموذج الرمز/الهجرة و Changelog جاهز.
• تمكين الاستنكار/غروب الشمس (الإصدار القديم) + كيفية ترحيل الصفحة.
• خطة الكناري/الظل، التنبيهات ولوحات القيادة التي تقارن المقاييس.
• يحتفظ بالتوافق الخلفي لفترة متفق عليها.
• خطة التراجع ومصفوفة المخاطر المتفق عليهما.

موجز

واجهة برمجة التطبيقات المستقرة هي عملية، وليست "مرة واحدة وإلى الأبد. "العيش وفقًا للقواعد: SemVer + التطور الإضافي فقط + سجل الدائرة + اختبارات العقد + إجراءات غروب الشمس. أنماط منفصلة (REST/gRPC/GraphQL) وسياساتها، إصدارات المسار إلى واجهة برمجة التطبيقات البوابة، طرح جزر الكناري، قياس التأثير. بهذه الطريقة ستتجنب «كسر المفاجآت»، وتسريع تكامل الشركاء والحفاظ على القدرة على التنبؤ بالمجالات النقدية والامتثال الحرجة.