نسخه API و سازگاری قرارداد

TL ؛ دکتر متخصص

سازگاری انضباط است، نه شانس. یک سیاست نسخه روشن (SemVer) را حفظ کنید، ریاضی را تغییر دهید (چه چیزی «شکسته»، چه چیزی نمی کند)، تست قرارداد، ثبت طرح و روش های غروب آفتاب. برای پول و انطباق - REST/gRPC سخت با vN، برای تجمع UI - GraphQL تکاملی با «@ مستهلک». همیشه: ترافیک قناری، سازگاری عقب ≥ یک چرخه انتشار، راهنماهای مهاجرت، تله متری میدان.

1) مفاهیم و اهداف اساسی

Backward-compatible (BC): کلاینتهای قدیمی برای سرور جدید مناسب هستند.
سازگار با جلو (FC): مشتریان جدید برای سرور قدیمی (محدود) مناسب هستند.
سازگاری سیم: فرمت در «سیم» شکسته نمی شود (مخصوصا برای gRPC/Protobuf مهم است).
SemVer: سرگرد. جزئی است. پچ - شکستن قرارداد → افزایش عمده.

هدف به حداقل رساندن تغییرات مخرب و ارائه پنجره مهاجرت قابل پیش بینی است.

2) تغییر ماتریس: آنچه شما می توانید و نمی توانید

3) سیاست ها برای سبک های مختلف API

3. 1 استراحت

نسخه در URI ('/v1/... ') یا دامنه (' api-v1. '). نسخه سربرگ - فقط برای موارد داخلی.
اضافه کنید، حذف نکنید: زمینه های جدید - خوب، قدیمی - علامت به عنوان 'مستهلک' در نمودار و ترک برای حداقل یک چرخه.
وضعیت ها/خطاها: کدها و structure 'error را تغییر ندهید. کد/خطا پیام/خطا جزئیات.
Idempotency بدون تغییر است: یک POST امن با «Idempotency-Key» را به یک چالش «رفتاری متفاوت» تبدیل نکنید.

3. 2 gRPC/Protobuf

اعداد فیلد مقدس هستند: از اعداد حذف شده استفاده نکنید، علامت به عنوان «رزرو شده».
فقط اضافه کردن زمینه های اختیاری/repit جدید ؛ «سخت اجباری» - از طریق اعتبار، نه «required».
بسته های نسخه: "پرداخت. v1، پرداخت ها. V2 '.
سازگاری سرویس: RPC های جدید → یک روش جدید ؛ ما رفتار قدیمیها را تغییر نمیدهیم.

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 GraphQL

تکامل بدون v2: اضافه کردن زمینه ها/انواع ؛ حذف - از طریق '@ deprecated (دلیل)' با اعلام پنجره.
پرس و جوهای مداوم: برای مشتریان عمومی، از لیست سفید پرس و جوها استفاده کنید - کنترل سازگاری آسان تر است.
سطح میدان 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 ').
امضاها/NMAS را بدون تغییر نگه دارید الگوریتم های جدید - به عنوان یک گزینه با پرچم.
Extensions - فقط از طریق داده های فیلدهای جدید. 'و' هدر '- بدون حذف آنهایی که قدیمی است.

4) دروازه API و مسیریابی نسخه

مسیریابی مبتنی بر قوانین: با پیشوند «/v1 »، با هدر« X-Api-Version »، توسط دامنه.
Shadow/Canary: بازتاب برخی از ترافیک تولید در نسخه جدید «به سایه ها»، پاسخ ها را مقایسه کنید.
نرخ/سهمیه در هر نسخه: محافظت از مشتریان قدیمی تر در طول مهاجرت.

• 'Sunset: ' - تاریخ خاموش شدن نسخه
• «استهلاک: درست» - نسخه منسوخ می شود
• 'پیوند: ؛ rel = "استهلاک" "- در changelog/راهنمای مهاجرت

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 для REST ؛ توصیف کننده های Protobuf для gRPC ؛ رجیستری SDL для GraphQL

CI چک: linters + «شکستن تغییرات چک» در روابط عمومی.
قراردادهای مبتنی بر مصرف کننده (CDC): تست های مصرف کننده (پیمان/آنالوگ) - محافظت در برابر وقفه های غیر قابل توجه.
Changelog: ماشین قابل خواندن (به عنوان مثال، 'CHANGELOG. md '+ یادداشتهای انتشار در رجیستری).

6) تکامل زمینه ها: قوانین انگشت شست

ID/keys: فرمت (UUID↔int) را بدون یک فیلد جدید '_ v2' و یک دوره انتقال تغییر ندهید.
زمان/ارز: نگه داشتن UTC ISO-8601/epoch و amount_minor + ارز ؛ مقیاس نیست (پنی/سنت).
Enum: اضافه کردن ارزش ها - خوب ؛ معنی کلمات قدیمی را تغییر ندهید. برای REST، مقادیر رشته را بدهید، نه ints.
صفحه بندی: مبتنی بر مکان نما با ثبات تر ؛ معناشناسی مکان نما را تغییر ندهید.

7) روش تخلیه و «غروب آفتاب»

1. اعلامیه (T-90/60): changelog، ارسال نامه به شرکا، عناوین «استهلاک/غروب آفتاب».
2. دوره تکراری: V1 و V2 به صورت موازی عمل می کنند ؛ V1 با هشدارها در پاسخ/سیاهههای مربوط مجهز شده است.
3. استفاده از تله متری: چه کسی دیگر V1 را صدا می کند ؟ نقطه تماس.
4. انجماد V1: فقط رفع اشکال/هیچ ویژگی.
5. Sunset-410 صفحه بلوک دستورالعمل رفته یا مهاجرت.

8) انتشار بدون درد: استراتژی های تخمگذار

مسیریابی آبی/سبز یا وزنی: 1-5-25-50-100٪ ترافیک.
پنجره سازگاری: حداقل 1-2 نسخه جزئی، اغلب 6-12 ماه برای API های خارجی.
ویژگی پرچم شامل زمینه های منطق جدید/شاخه بدون ارتقاء.
خواندن/نوشتن تقسیم: برای اولین بار اضافه کردن پشتیبانی برای خواندن یک فیلد جدید، سپس شروع به نوشتن آن.

9) تست قابلیت همکاری (مجموعه تمرین)

تست طلایی برای پاسخ از نسخه های قدیمی تر.
تست تفاوت مدارها: بدون شکستن در CI.
تولید پخش اجرا می شود در مرحله بندی برای V2 (سایه).
اسکریپت های عقب/جلو: مشتری جدید در سرور قدیمی و بالعکس (که در آن FC معتبر است).
تست های قرارداد وب سایت ها: تأیید امضا، فرمت، زمان.

10) معیارها و SLO ها از روند نسخه

٪ از مشتریان در آخرین MINOR (≥ هدف 80٪ قبل از غروب آفتاب).
خطاهای سازگاری/عدم دسترسی در هر انتشار (هدف 0).
سهم تماس های میراث (کاهش به غروب آفتاب).
زمان مهاجرت مشتری (میانه/p95).
دلتا تاخیر/رگرسیون بین نسخه ها (نه بدتر از پایه).

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 تصریح شده است.
رویدادها/جریانها (WS/Kafka): نسخه in 'envelope. نسخه ؛ ویژگی های جدید - اختیاری ؛ dedup و رزومه کار یکسان بین نسخه.
گزارش/CSV: نسخه در نام فایل/هدر ؛ افزودن ستونها به راست ترتیب/انواع را تغییر نمیدهد.

13) حکومت و نقش

مالک قرارداد (مالک دامنه)، API کارگزار (قوانین و لاینترها)، مدیر انتشار (غروب آفتاب/ارتباطات).
فرآیند RFC برای شکستن تغییرات: توجیه کسب و کار، طرح مهاجرت، مصنوعات، تاریخ.
دایرکتوری API یکپارچه: که در آن نمودارها، نسخه ها، تقویم غروب آفتاب، تماس قابل مشاهده است.

14) ضد الگوهای

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

15) چک لیست انتشار نسخه جدید

• طرح به روز شده (OpenAPI/Protobuf/SDL)، خطوط و چک های شکستن گذشت.
• تست های ادغام و قرارداد (CDC) اضافه شده است.
• SDK/کد نمونه/راهنمای مهاجرت و Changelog آماده است.
• استهلاک/غروب آفتاب را فعال کنید (نسخه قدیمی) + چگونه به مهاجرت صفحه.
• Canary/Shadow plan، هشدارها و داشبورد مقایسه معیارها.
• سازگاری عقب مانده برای یک دوره توافق شده حفظ می شود.
• طرح بازگشت و ماتریس ریسک توافق شده است.

خلاصه

یک API پایدار یک فرآیند است، نه «یک بار و برای همه». "زندگی با قوانین: SemVer + اضافه کردن تنها تکامل + ثبت مدار + تست قرارداد + روش غروب آفتاب. سبک های جداگانه (REST/gRPC/GraphQL) و سیاست های آنها، نسخه های مسیر به API دروازه، رول کردن قناری ها، اندازه گیری اثر. به این ترتیب شما از «شکستن شگفتی» جلوگیری می کنید، سرعت ادغام شریک را افزایش می دهید و قابل پیش بینی بودن حوزه های پولی و انطباق را حفظ می کنید.