استراتژی های نسخه بندی API

چرا نسخه مورد نیاز است

API سریعتر از مشتریان تغییر می کند. نسخه بندی اجازه می دهد تا شما را به انتشار ویژگی ها و ویرایش اشتباهات بدون شکستن ادغام، مجموعه مراسم تغییر و باعث می شود تکامل قابل پیش بینی است. کلید: تغییرات افزودنی پیش فرض, رشته های اصلی - برای شکستگی تنها, چک سازگاری خودکار و سیاست غروب متفکر.

اصول اساسی

1. افزودنی اول: زمینه های جدید اختیاری/روش ها/رویدادها - خوب ؛ حذف و معنی تغییر - عمده.
2. MGC (حداقل قرارداد گارانتی) پایدار است ؛ غنی سازی - از طریق توانایی ها/' ؟ شامل = '.
3. خواننده تحمل: مشتریان زمینه های ناشناخته را نادیده می گیرند و به درستی از پسوند enum زنده می مانند.
4. نسخه معنایی: 'MAJOR. جزئی است. PATCH برای مصنوعات، SDK ها و رویدادها.
5. خودکار سازی: تست های schema-diff، linters و CDC تغییرات شکستن را مسدود می کنند.

که در آن برای ذخیره نسخه (آدرس مکانیک)

استراحت/HTTP

نسخه URI: «/v1/سفارشات »→ آسان به مسیر، مناسب در دروازه. منفی - «مبهم» تکامل ایده ها.

رسانه/هدر: 'پذیرش: برنامه/vnd. به عنوان مثال. دستورات. v1 + json '- کنترل دقیق فرمت ؛ سخت تر برای تحقیر کردن

نسخۀ پرسوجو: '؟ API-version = 1 '- مناسب برای A/B، اما آسان برای از دست دادن در کش/سیاهههای مربوط.
توصیه: URI برای خطوط اصلی + پرچم های ویژگی/قابلیت و نفی محتوا برای پسوند های جزئی.

gRPC/پروتوبوف

بسته ها/خدمات: "پرداخت بسته. v1 ؛ PaymentsV1 خدمات ؛ '- خطوط صریح.
شماره برچسب بدون تغییر است ؛ برچسب های حذف شده قابل استفاده مجدد نیستند.
زمینه های جدید - «اختیاری» ؛ شکستن → جدید '.v2'.

نمودار QL

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

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

نام رویداد: "پرداخت. مجاز است. v1 'نسخه در نوع است.
رجیستری طرح (Avro/JSON طرح/Protobuf) با حالت های سازگاری (BACKWARD/FORWARD/FULL).
Major → dual-emit «v1» و «v2» برای دوره انتقال.

مدل نسخه و سیاست تغییر

نسخهبندی معنایی

MAJOR - تغییرات شکستن: حذف/تغییر نام زمینه، تغییر کلید عضویت، معنای مختلف وضعیت، سفت اعتبار.
MINOR - افزودنی: زمینه های جدید اختیاری/نقاط پایانی/حوادث، مقادیر جدید enum با تحمل خواننده.
PATCH - رفع بدون تغییر قرارداد و معانی.

استهلاک و غروب آفتاب

علامت منسوخ («Deprecated: true»، «@ deprecated»)، تاریخ غروب آفتاب، جایگزین و راهنمای مهاجرت را منتشر کنید.
در HTTP - سرآیند 'Sunset', 'Deprecation'; در حوادث - جداگانه '.deprecation. توجه کنید.
استفاده از تله متری برای تصمیم گیری در مورد حذف.

استراتژی های نسخه بندی بر اساس سبک

استراحت کردن

خطوط اصلی در/v1 ،/v2.

MINOR: توسعه طرح، '؟ فیلدها = '،' ؟ شامل = '؛ افزونه های امن enum

ETag/If-Match و POST idempotent برای سازگاری غیر شکستگی.
خطاها - قالب پایدار («نوع»، «کد»، «ردیابی _ id»).

جی آر پی سی

معرفی خدمات/روش های جدید برای شکستن: PaymentsV2. دستگيري ".
وضعیت خطا و معانی مهلت بخشی از قرارداد است ؛ تغییر → روش جدید/خدمات.
جریان: در مورد سفارش پیام موافقت کنید و آن را به جزئی تغییر ندهید.

نمودار QL

فیلدها و انواع را آزادانه اضافه کنید deletions - از طریق «@ deprecated» + پنجره مهاجرت ؛ بازطراحی بزرگ → طرح جدید ('/graphql-v2 ').
خودآزمایی و توصیف - باید برای مهاجرت مشتری.

رویداد ها

هسته در مقابل غنی شده: هسته پایدار است، غنی زندگی می کنند در این نزدیکی هست و به طور جداگانه versioned.
کلید پارتیشن در خط اصلی بدون تغییر است.
مهاجرت عمده - «انتشار دوگانه» + پیش بینی/مهاجرت مصرف کننده.

پرچم های مذاکره و توانایی

قابلیت ها: مشتری می فرستد 'X-قابلیت ها: risk_score,price_v2' ؛ سرور با یک دید گسترده پاسخ می دهد.
ترجیح می دهم (HTTP) و نکات برای پاسخ های جزئی.
در سوکت/جریان - یک پیام دست دادن با یک لیست از برنامه های افزودنی پشتیبانی می شود.

انتشار نسخه های اصلی بدون درد

1. RFC/ADR: چرا عمده مورد نیاز است، چه چیزی شکسته، ماتریس ریسک.
2. اجرای دوگانه: راه اندازی موازی «v1» و «v2» (انتشار دو رویداد، دو مسیر دروازه، ترافیک معکوس).
3. آداپتورهای مهاجرت: پروکسی/مترجم «v1↔v2» برای مشتریان سنگین.
4. Canary: توسط گروه مشتری/موضوع/برچسب در دروازه.
5. طرح غروب آفتاب: تاریخ، ارتباطات، غرفه ها، داده های تست، نظارت بر استفاده.

نقش های بستر و زیرساخت

API دروازه/سرویس مش: مسیریابی توسط نسخه، هدر، مسیر ؛ محدودیت نرخ и 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).
مشاهده: نسخه باید در logs/trails/metrics گنجانده شود.

تست نسخه

طرحواره در روابط عمومی: شکستن بلوک.
قراردادهای مبتنی بر مصرف کننده: ارائه دهنده در برابر قراردادهای مصرف کننده واقعی آزمایش می شود.
نمونه های طلایی: پاسخ های مرجع به نسخه ها.
E2E canary: مقایسه p95/p99، خطاها و زمانهای بین نسخه ها.
پخش برای حوادث: پیش بینی ها به v2 با هیچ اختلاف دوباره مونتاژ.

مهاجرت داده ها و پایگاه داده

برای REST/gRPC: مهاجرت پایگاه داده از طریق گسترش و قرارداد هماهنگ می شود (اضافه کردن یک ستون → شروع نوشتن → خواندن سوئیچ → حذف قدیمی).
برای رویدادها: مهاجرت دوگانه و مهاجرت مصرف کننده ؛ گاهی اوقات - پخش ورود به سیستم در پیش بینی های جدید.
«انفجار بزرگ» را ایجاد نکنید - به مراحل با عقب نشینی تقسیم کنید.

رابطه امنیتی

اسرار/ادعاهای توکن بخشی از قرارداد است ؛ تغییر = بزرگ

حوزه در هر نسخه: فردی OIDC-حوزه/نقش برای V1/V2.
PII/PCI - بارگیری غیر ضروری را گسترش ندهید ؛ زمینه های جدید - با حداقل امتیازات.

ضد الگوهای

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

چک لیست پیش از انتشار

• تغییرات افزودنی هستند یا یک خط اصلی جداگانه آماده شده است.
• لینترها و schema-diff سبز هستند (شکستن خزیدن نیست).
• به روز شده SDK/نمونه/مستندات، پاورقی سازگاری.
• فعال خواننده تحمل در مشتریان ؛ enum-fallback تست شده است.
• برای عمده - طرح دو اجرا، آداپتورها، قناری، تاریخ غروب آفتاب و پستی.
• Metrics/logs/trails حاوی یک نسخه و تقسیم بندی توسط آن است.
• یک پایه و مجموعه طلایی برای مقایسه v1↔v2 وجود دارد.
• برای رویدادها، رجیستری طرح در حالت BACKWARD/FULL است، کلیدهای پارتیشن بدون تغییر هستند.

نمونه قالب ها

استراحت (URI + مذاکره)

مسیر: '/api/v2/orders/{ id} '

Заголовок: 'ترجیح می دهند: شامل = موارد، مشتری'، 'قابلیت های X: risk_score'

استهلاک: 'غروب آفتاب: 2026-06-30'، 'لینک: ؛ rel = «جایگزین»

Protobuf/gRPC

proto package payments.v2;

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

رویداد ها

حق الزحمه. دستگیر شد. v2 (هسته) و «پرداخت». غنی شده v2 '(جزئیات).
برای دوره انتقال، تولید کننده می رود «v1» و «v2».

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

چه زمانی «/v2 »مورد نیاز است ؟

هنگامی که invarians/semantics تغییر می کند، زمینه ها/روش ها حذف می شوند، فرمت شناسه ها، کلید پارتیشن بندی، SLA/زمان بندی تغییر می کند به طوری که مشتریان شکستن.

آیا می توانید بدون نسخه صریح در REST زندگی کنید ؟

فقط برای سیستم های کوچک برای یکپارچگی خارجی، خطوط اصلی صریح بهتر هستند.

چه مدت طول می کشد تا نسخه قدیمی را نگه دارید ؟

بستگی به اکوسیستم دارد. برای شرکای خارجی، معمولا 6-12 ماه با اطلاع رسانی اولیه و قناری.

چگونه نسخه رویداد از API متفاوت است ؟

رویدادها - فقط ضمیمه ؛ معانی جدید = نوع جدید '.v2' و dual-emit. کلید تقسیم بخشی از قرارداد است.

نتیجه گیری

استراتژی های نسخه بندی فرآیند و ابزار هستند: تکامل افزودنی پیش فرض، خطوط اصلی روشن، مذاکره قابلیت، دوگانه و غروب آفتاب. اضافه کردن چک سازگاری خودکار، تله متری استفاده، و نظم و انضباط اسناد و مدارک - و API های خود را به سرعت تکامل خواهد یافت، بدون «مهاجرت شب» و قطره غیر منتظره در مشتریان.