سازگاری عقب

سازگاری عقب چیست

سازگاری با عقب - ویژگی سیستم برای پذیرش و پردازش صحیح مشتریان/مصرف کنندگان قدیمی هنگامی که سیستم به روز می شود. ساده تر: شما یک نسخه جدید از خدمات/رویدادها را منتشر می کنید و ادغام های موجود همچنان بدون تغییر کار می کنند.

نکته کلیدی: قراردادها را نقض نکنید. هر تکامل از طریق اضافه کردن، و نه بازسازی، یک در حال حاضر منتشر شده است.

اصول اساسی

1. افزودنی اول

فیلدها/روش ها/رویدادهای جدید به صورت اختیاری اضافه می شوند. هیچ چیز موجود حذف نمی شود و معنی را تغییر نمی دهد.

2. حداقل قرارداد گارانتی (MGC)

تعریف یک هسته - مجموعه ای از زمینه ها/عملیات که بدون آن اسکریپت معنای خود را از دست می دهد. هسته ثابت است. هر چیز دیگری توسعه است.

3. خواننده تحمل پذیر

مشتریان فیلدهای ناشناخته را نادیده می گیرند و به درستی مقادیر جدید enum (fallback) را مدیریت می کنند.

4. سیاست نسخه ها

شکستن تغییرات - فقط از طریق خط اصلی ("/v2 "،" پرداخت. v2 '،' رویداد. v2 '). جزئی - افزودنی.

5. قابلیت مشاهده - بخشی از قرارداد

نسخه مشتری، فرمت، پرچم قابلیت در سیاهههای مربوط/آهنگ و معیارهای قابل مشاهده است. این به شما امکان می دهد مهاجرت خود را مدیریت کنید.

امن در مقابل تغییرات خطرناک

به طور کلی امن (BC-OK)

فیلدهای اختیاری را اضافه کنید (JSON/Avro/Protobuf «اختیاری »/« nullable»).
افزودن نقاط پایانی/روشها/رویدادهای جدید.
پسوند Enum با مقادیر اضافی (با خواننده تحمل).
تضعیف اعتبار (به حداکثر رساندن، اضافه کردن فرمت های جایگزین).
اضافه کردن هدر های غیر معنی دار/ابرداده.

خطرناک (شکستن)

حذف/تغییر نام فیلدها، تغییر نوع یا اجباری از زمینه های موجود.
تغییر معنای کد وضعیت/خطا.
استفاده مجدد از برچسب های protobuf برای زمینه های دیگر.
تغییر کلید پارتیشن بندی رویداد (ترتیب جمع را خراب می کند).
تشدید SLA/زمان بندی، باعث می شود مشتریان قدیمی شروع به سقوط کنند.

با سبک های تعامل

REST/HTTP + JSON

Additivity: زمینه های جدید - «اختیاری»، سرور آنها را از مشتریان قدیمی نیاز ندارد.
نسخه ها: عمده - در حمل و نقل ('/v2 ') و یا نوع رسانه ؛ minor - از طریق برنامه های افزودنی و '؟ شامل = '/' ؟ فیلدها = '.
خطاها: فرمت یکنواخت ؛ کدها/معانی را بدون عمده تغییر ندهید.
ETag/If-Match: برای به روز رسانی امن بدون مسابقه.
Idempotency: «Idempotency-Key» برای POST - مشتریان قدیمی «دو برابر» اثر در عقب نشینی نیست.

gRPC/Protobuf

برچسب ها بدون تغییر هستند. برچسبهای حذف شده قابل استفاده مجدد نیستند.
زمینه های جدید - «اختیاری »/« تکرار» ؛ مقادیر پیش فرض به درستی توسط کد قدیمی انجام می شود.
Streaming: ترتیب/تعهد پیام ها را در minor تغییر نمی دهد.
خطاها - مجموعه ای پایدار از وضعیت ها ؛ معناشناسی جدید → روش/سرویس جدید ('.v2').

رویداد محور (کافکا/NATS/پولسار) + آورو/JSON/پروتو

نام گذاری: دامنه فعالیت. v {سرگرد}.
هسته در مقابل غنی شده: هسته پایدار ؛ غنی سازی - انواع/تم های فردی («غنی شده»).
حالت سازگاری طرح: اغلب BACKWARD ؛ CI تغییرات ناسازگار را مسدود می کند.
تقسیم بندی: کلید (به عنوان مثال، 'payment _ id') - بخشی از قرارداد ؛ آن را تغییر دهید - شکستن.

GraphQL

اضافه کردن فیلدها/انواع - OK ؛ حذف/تغییر نام دهید - از طریق «مستهلک» و پنجره مهاجرت.
«nullable → non-nullable» را بدون major مطرح نکنید.
نظارت بر پیچیدگی/عمق - تغییر محدود = تغییر قرارداد.

الگوهای برای کمک به حفظ BC

مدل هرم معکوس: هسته را تثبیت کنید، به صورت اختیاری گسترش دهید.
مذاکره قابلیت: مشتری قابلیت های پشتیبانی شده («قابلیت های X »/دست دادن) را گزارش می دهد، سرور تنظیم می کند.
Dual-run/dual-emit: در طول مهاجرت «v1» و «v2» را همزمان نگه دارید.
آداپتورها: پروکسی ها/دروازه ها درخواست های «v1↔v2» را برای مشتریان «سنگین» ترجمه می کنند.
Expand-and-contract (برای DB): ابتدا یک مورد جدید اضافه کنید، شروع به نوشتن/خواندن کنید، فقط پس از آن قدیمی را حذف کنید.

حکومت و فرآیند

1. کاتالوگ قرارداد (Schema Registry): یک منبع واحد حقیقت با سیاست های سازگاری.
2. Linters و diff چک در CI/CD: OpenAPI-diff, Buf-breaking, Avro/JSON بررسی سازگاری طرح.
3. CDC/قراردادهای مبتنی بر مصرف کننده: ارائه دهنده برای قراردادهای مصرف کننده واقعی آزمایش می شود.
4. نمونه های طلایی: نمایش داده شد مرجع/پاسخ/حوادث برای رگرسیون.
5. مدیریت تغییر: RFC/ADR در شکستن، برنامه های غروب آفتاب، ارتباطات.

Deprekate و حذف نسخه های قدیمی

علامت منسوخ («@ deprecated»، توصیف، هدر «Deprecation»، «Sunset»).
پنجره مهاجرت: تاریخ از پیش اعلام شده، نیمکت تست، نمونه های کد.
استفاده از تله متری: چه کس دیگری در 'v1' است ؟ معیارهای بخش/سیاهههای مربوط به نسخه.
دو اجرا به صفر ترافیک، و سپس حذف.

قابلیت مشاهده و معیارهای عملیاتی

درصد درخواست ها/پیام ها بر اساس نسخه

سهم خطاها/زمان برای مشتریان قدیمی پس از انتشار.
نسبت بار ناسازگار (اعتبارسنجی توسط طرح روی فیلترهای دروازه/جریان).
تاخیر مهاجرت مصرف کننده (چند نفر دیگر به «v1» گوش می دهند).

تست سازگاری عقب

Schema-diff: خرابی при حذف/تغییر نام/تغییر نوع.
تست قرارداد: SDK های قدیمی/مشتریان در برابر اجرای جدید رقابت می کنند.
قناری E2E: بخشی از ترافیک قدیمی به نسخه جدید، مقایسه p95/p99، کد، retrays.
پخش رویداد: پیش بینی ها با منطق جدید از ورود به سیستم قدیمی بدون اختلاف جمع آوری می شوند.
تزریق خطا: تاخیر/پاسخ جزئی - مشتریان قدیمی سقوط نمی کنند.

مثال ها

REST (افزودنی)

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

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

مشتریان قدیمی، با نادیده گرفتن «risk _ score»، به کار خود ادامه می دهند.

Protobuf (برچسب ها)

proto message Payment {
string id = 1;
string status = 2;
optional double risk_score = 3 ;//new field, safe
}
//Tags 1 and 2 cannot be changed/deleted without v2

رویدادها (هسته + غنی سازی)

حق الزحمه. مجاز است. v1 '- هسته (حداقل حقایق).
حق الزحمه. غنی شده v1 '- قطعات ؛ مصرف کنندگان اصلی وابسته به غنی سازی نیستند.

ضد ضربه

Swagger-wash: این طرح به روز شده است، اما سرویس به روش قدیمی رفتار می کند (یا برعکس).
شکاف های پنهان: معنای فیلد/وضعیت را بدون نسخه تغییر داد.
استفاده مجدد از برچسب های protobuf: فساد اطلاعات «آرام».
مشتریان سخت: سقوط در زمینه های نا آشنا/enum ؛ بدون خواننده تحمل.
نقطه پایانی مگا: یک همه در یک - هر تغییری به یک ضایعات بالقوه تبدیل می شود.

چک لیست قبل از انتشار

• تغییرات افزودنی هستند ؛ هسته (MGC) دست نخورده است.
• خطوط/چک های مختلف گذشت ؛ هیچ پرچمی شکسته نمی شود.
• SDK های مشتری به روز شده اند (یا برای پسوند افزودنی لازم نیست).
• فعال خواننده تحمل برای مشتریان ؛ دوباره چک شد.
• متریک/سیاهههای مربوط حاوی نسخه و پرچم قابلیت.
• برای شکستگی احتمالی «/v2 »، طرح دوگانه و غروب خورشید وجود دارد.
• مستندات/نمونه ها به روز شده اند، مجموعه های طلایی وجود دارد.

سوالات متداول

عقب در مقابل جلو - تفاوت چیست ؟

Backward - سرورهای جدید با مشتریان قدیمی کار می کنند. مشتریان جدید به درستی با سرورهای قدیمی کار می کنند (به دلیل خواننده تحمل و پیش فرض های شسته و رفته). دایره کامل - سازگاری کامل.

آیا همیشه باید «/v2 »را برای تغییرات بزرگ انجام دهم ؟

بله، اگر invariants/type/keys/semantics شکستن. در غیر این صورت، خط را نگه دارید و به طور افزایشی تکامل دهید.

چه در مورد enum ؟

ارزش های جدید را بدون تغییر معنای قدیمی ها اضافه کنید. مشتریان باید در یک ارزش ناشناخته سقوط کنند.

اگر شما در حال حاضر «شکسته»?
رول بک، آداپتور hot-fix، انتشار «v2» با راهنمای دوگانه، ارتباطات و مهاجرت.

مجموع

سازگاری عقب مانده نظم و انضباط تکامل است: تثبیت هسته، گسترش additively، پیاده سازی یک خواننده تحمل، خودکار چک و حفظ آگاهانه مستهلک. به این ترتیب شما می توانید به سرعت توسعه پلت فرم بدون ترک مشتریان زیر آوار از تغییرات «نامرئی».