توافق وتحديثات واجهة برمجة التطبيقات
1) أساسيات التوافق
إضافة أولاً: إضافة جديدة دون كسر قديم (حقول/نقاط نهاية اختيارية جديدة، قيم جديدة).
العقود الثابتة: «ما يعد به في أعمال المواصفات» ؛ تم توثيق السلوك.
إلى الأمام: أولوية التوافق إلى الخلف ؛ إلى الأمام من خلال القراء المتسامحين.
المستندات أساسية: المصدر الوحيد للحقيقة هو نسخة السجل من المخطط (OpenAPI/AsyncAPI/Proto).
تطور صريح: اختراق - فقط من خلال نسخة رئيسية جديدة ودليل الهجرة.
2) تصنيف التغييرات
2. 1 متوافقة (MINOR/PATCH)
أضف حقول/رؤوس اختيارية ونقاط نهاية جديدة ومعلمات استعلام مع افتراضات.
زيادة الحدود («الصفحة _ الحجم»، TTL)، توضيح الأخطاء دون تغيير الرموز/الدلالات.
أضف قيم enum إذا تجاهل العملاء «المجهول» (القارئ المتسامح).
2. 2 غامض (سلوكي)
تغيير التخلف عن السداد، ترتيب الفرز، المهلات الضئيلة، الحصص - يمكن أن «يكسر» منطق العمل. يتطلب إعلان RFC + وكناري.
2. 3 كسر (رئيسي)
إعادة تسمية/حذف الحقول، تغيير النوع/الشكل، استبدال رموز الخطأ، عكس عدم توافق العقود/مخططات التوثيق.
3) سياسة التحديث
الاستراتيجية: «إصدار المسار» («/v1 »، «/v2»).
Minor/patch: «إضافة، لا تنكسر».
العناوين المؤرخة (اختياري): «X-API-Version-Date» للتغييرات التدريجية الناعمة.
أنواع الوسائط (Op.): 'Application: application/vnd. acme. v1 + json 'للحبيبات الدقيقة.
4) الاستنكار وغروب الشمس
4. 1 رؤوس اتصالات
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"4. 2 أمر الانسحاب
1. الإعلان في البوابة/القائمة البريدية/مذكرات إصدار SDK.
2. نافذة التحذير ≥ 90-180 يوما.
3. حالات في لوحة عدادات التبني.
4. بعد غروب الشمس - 410 ذهب أو وضع «القراءة فقط» لفترة السماح، إذا تم الاتفاق.
5) الهجرة والتعايش بين النسخ
مزدوج الكتابة/مزدوج القراءة في المرحلة الانتقالية والتوفيق مع التقارير.
محولات (مؤقتة): تحويل بوابة الحمولة القديمة → مخططات جديدة ؛ عمر المحول محدود.
مساعدة SDK: الإصدارات التي تدعم كلا الإصدارين، مع تحذيرات من الانخفاض (وقت 1 لكل عملية).
أعلام الميزة: إدراج دلالات جديدة وفقًا لقائمة المفاتيح/المستأجرين.
6) التوافق الخلفي والأمامي
6. 1 إلى الوراء (العملاء القدامى ↔ الخادم الجديد)
لا تغير النماذج النمطية/الإلزامية.
الحقول الجديدة اختيارية فقط.
الأخطاء - «خطأ _ رمز» قديم، إضافة رموز جديدة، لا تحل محل.
6. 2 إلى الأمام (عملاء جدد ↔ خادم قديم)
تحقق من القدرات من خلال «الخيارات »/«/الإصدارات».
سلوك النعمة: يجب أن يكون العميل متسامحًا مع الميزات المفقودة.
7) العقود والفحوصات التلقائية
السجل: نسخ مخططات التخزين ؛ يحفر العلاقات العامة → تقارير كسر/عدم كسر.
البطانة: الأسماء/الأنواع، الخصوصية، التثبيت، الرموز المستقرة.
CDC (العقود التي يحركها المستهلك): اختبارات التكامل في CI للمورد (الميثاق والنظائر).
البوابة: يتم حظر العلاقات العامة عند كسرها بدون «نتوء كبير »/RFC.
yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml8) امتداد الكناري وعكسه
الكناري: 10٪ → 25٪ → 50٪ → 100٪ من حركة المرور ؛ التراجع التلقائي عن تحلل SLO (5xx/latency/429).
مفاتيح بيتا: الوصول إلى إصدارات جديدة بواسطة allowist.
تجميد الإصدار: ميزانية خطأ أثناء الاحتراق.
تحليلات القبول: حصة حركة المرور/العملاء في الإصدار الجديد، وقت الترحيل.
9) التوافق بالتفصيل: الأخطاء، التثبيت، الغباء
9. 1 أخطاء
لا تغير حالات HTTP في النصوص الحالية.
«خطأ _ رمز» - مستقر ؛ الرموز الجديدة تضاف فقط.
«تطبيق/مشكلة + جسون» هو تنسيق واحد.
9. 2 التثبيت
التبديل إلى مؤشر/keyset = MINOR إذا تم دعم "offset/limit' القديم.
قم بتوثيق النوع «(updated_at,id)» واستقرار المؤشر.
9. 3 الخصوصية
للكتابة - «Idempotency-Key» + '409 IDEMP_REPLAY' في حالة الصراع.
يجب ألا تغير الهجرات دلالات الغباء.
10) تحولات البوابة (عند الاقتضاء)
خريطة v1→v2 الحقول، تطبيع الأخطاء، تحويل التاريخ/تنسيقات النقود.
حواجز الحماية: التحولات شفافة ومنطقية ؛ لا تخفي الكسر، بل تستخدم كجسر محدود المدة.
11) الاتصالات والبوابة
Changelog с датами («تمت إضافته/تغييره/نقضه/إزالته/ثباته»).
بطاقة الإصدار: الحالة (بيتا/GA/disprected)، تاريخ الغروب، روابط إلى أدلة.
خطوط الويب للإخطار: "الاستنكار. «،» نسخة. «،» خطة. '.
ملاحظات إصدار SDK + لافتة بوابة.
12) مقاييس النجاح
معدل التبني v2 (لكل طلب/عميل).
حوادث متخلفة.
مزيج الخطأ (4xx/5xx/429 مشاركة) قبل/بعد الإصدار.
حان الوقت لاعتماد المتوسط.
حمولة الدعم (تذاكر/أسبوع).
تكلفة الخدمة.
13) النماذج والأمثلة
13. 1 عناوين النسخة والتخفيضات
X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"13. 2 سياسة النسخة (جزء YAML)
yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]13. 3 ملحق ميداني OpenAPI متوافق
yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive14) قائمة مرجعية للإصدار (MINOR/MAJOR)
قاصر
- DIFF: غير مكسور، بطانة خضراء
- تم تحديث الوثائق/SDK (أمثلة/ترميز)
- تراجع Canary + auto-SLO
- Comm Plan، صفحة البوابة
- لوحات معلومات التبني والخطأ
الرائد
- RFC/ADR، تاريخ غروب الشمس ونافذة ≥90 -180 يومًا
- دليل الجسر والهجرة v1↔v2
- الكتابة المزدوجة/القراءة والتسويات
- SDK مع تنبيهات واجهة برمجة التطبيقات +
- تجربة مع جهات التكامل الرئيسية
15) خطة التنفيذ (3 تكرارات)
1. المؤسسة (2 أسابيع):
) أ (تسجيل المخططات والوصلات والاختزال التلقائي في جزر المحيط الهادئ ؛ وسياسة التوافق ؛ عناوين «الاستنكار/غروب الشمس».
2. الإصدارات المدارة (3-4 أسابيع):
جزر الكناري، الأعلام المميزة، تنبيهات SLO ؛ وبوابة النسخة ؛ تصدر SDK بدعم من الفروع 2.
3. التشغيل الآلي والحجم (المستمر):
اختبارات CDC للمستهلكين في CI، وتوقعات غروب الشمس بشأن اتجاهات التبني، والإشعارات التلقائية والتذكيرات.
16) الأسئلة الشائعة المصغرة
هل يمكنني تغيير نوع الحقل بدون تخصص ؟
لا ، ليس كذلك حتى «stroka→chislo» ينكسر. أدخل حقل جديد، القديم مهين.
Enum: هل يمكنك إضافة قيم ؟
نعم، إذا كان العملاء قراء متسامحين. خلاف ذلك - أولاً تنبيه وبيتا.
ما مقدار الاحتفاظ بالنسخة القديمة ؟
حتى الآن، تم الحفاظ على اعتماد ≥95٪ الجديدة. حدد الموعد النهائي في السياسة.
المجموع
التوافق مع API هو نظام: نهج إضافي، ومخططات رسمية وdiphs، وإطلاقات الكناري، وانخفاضات واضحة، والهجرات المدارة. دمج سياسات التغيير، وأتمتة الفحوصات والاتصالات، وقياس التبني - وستتوقف تحديثاتك عن كسر العملاء، وستزداد سرعة التطور دون فقدان الموثوقية.