سازگاری API و به روز رسانی

1) اصول سازگاری

افزودنی اول: اضافه کردن جدید بدون شکستن قدیمی (زمینه های جدید اختیاری/endpoints، مقادیر جدید enum).

قراردادهای پایدار: «آنچه که در مشخصات کار وعده داده شده ؛» رفتار مستند شده

عقب> به جلو: اولویت سازگاری عقب ؛ به جلو از طریق خوانندگان تحمل مجاز است.
اسناد اولیه هستند: تنها منبع حقیقت نسخه رجیستری طرح (OpenAPI/AsyncAPI/Proto) است.
تکامل صریح: شکستن - تنها از طریق یک نسخه اصلی جدید و یک راهنمای مهاجرت.

2) طبقه بندی تغییرات

2. 1 سازگار (MINOR/PATCH)

اضافه کردن زمینه های اختیاری/هدر، نقاط پایانی جدید، پارامترهای پرس و جو با پیش فرض.
افزایش محدودیتها ('page _ size', TTL)، روشن کردن خطاها بدون تغییر کدها/معانی.
اضافه کردن ارزش enum اگر مشتریان چشم پوشی از «ناشناخته» (تحمل خواننده).

2. ۲ مبهم (رفتاری)

تغییر پیش فرض ها، مرتب سازی مرتب سازی، زمان های نازک، سهمیه ها - می تواند منطق کسب و کار را «شکستن». نیاز به اعلان RFC + و قناری.

2. 3 شکستن (عمده)

تغییر نام/حذف فیلدها، تغییر نوع/فرمت، جایگزینی کدهای خطا، ناسازگاری معکوس قراردادها/طرح های احراز هویت.

3) سیاست نسخه

استراتژی: 'path versioning' ('/v1 ', '/v2').
جزئی/پچ: «اضافه کردن، شکستن نیست».
سرآیند تاریخ دار (اختیاری): 'X-API-Version-Date' برای تغییرات تدریجی نرم.
انواع رسانه ها (Op.): 'Accept: 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 عقب (مشتریان قدیمی ↔ سرور جدید)

نوع فرمت/اجباری را تغییر ندهید.
فیلدهای جدید فقط اختیاری هستند.
خطاها - 'error _ code' قدیمی، کدهای جدید اضافه کنید، جایگزین نکنید.

6. 2 به جلو (مشتریان جدید ↔ سرور قدیمی)

بررسی قابلیتها از طریق «OPTIONS »/«/versions».
رفتار گریس: مشتری باید تحمل ویژگی های گم شده را داشته باشد.

7) قراردادها و چک های اتوماتیک

رجیستری: نسخه های طرح فروشگاه ؛ PR digs → گزارش های شکستن/عدم شکستن.
Linter: نام/نوع، idempotency، صفحه بندی، کدهای پایدار.
CDC (Consumer-Driven Contracts): تست های Integrator در CI تامین کننده (Pact and Analogs).
دروازه: PR هنگام شکستن بدون «دست انداز »/RFC مسدود می شود.

yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml

8) گسترش قناری و معکوس

قناری: 10٪ → 25٪ → 50٪ → 100٪ از ترافیک ؛ بازگشت خودکار به تخریب SLO (5xx/latency/429).
کلید های بتا: دسترسی به نسخه های جدید توسط allowlist.
انجماد آزاد: خطا در بودجه در طول احتراق.
تجزیه و تحلیل پذیرش: سهم ترافیک/مشتریان در نسخه جدید، زمان مهاجرت.

9) سازگاری در جزئیات: خطاها، صفحه بندی، idemotence

9. 1 خطا

وضعیت HTTP را در اسکریپت های موجود تغییر ندهید.
'error _ code' - پایدار ؛ کدهای جدید فقط اضافه می شوند.
'application/problem + json' یک فرمت واحد است.

9. 2 صفحه بندی

اگر «آفست/حد» قدیمی پشتیبانی میشود، به مکاننما/keyset = MINOR سودهی کنید.
سند مرتب سازی '(updated_at,id)' و ثبات مکان نما.

9. 3 عدم توانایی

برای نوشتن - 'Idempotency-Key' + '409 IDEMP_REPLAY' در صورت درگیری.
مهاجرت نباید معنای قدرت را تغییر دهد.

10) تحولات دروازه (در صورت لزوم)

نقشه v1 → v2 زمینه, عادی خطاها, تبدیل فرمت های تاریخ/پول.
Guardrails: تحولات شفاف و منطقی هستند ؛ شکستن را پنهان نکنید، اما به عنوان یک پل زمان محدود استفاده کنید.

11) ارتباطات و پورتال

Changelog с датами («اضافه شده/تغییر یافته/منسوخ/حذف شده/ثابت»).
کارت نسخه: وضعیت (بتا/GA/مستهلک), تاریخ غروب آفتاب, لینک به راهنماهای.
صفحات اطلاع رسانی: "تخفیف. توجه داشته باشید '،' نسخه. نقشه آزاد شد. تغییر کند.
یادداشت انتشار 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 Field سازگار است

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+" } # additive

14) چک لیست انتشار (MINOR/MAJOR)

جزئی

• DIFF: غیر شکستن، سبز سبز
• مستندات/SDK به روز شده (نمونه/کدک)
• قناری + بازگشت خودکار SLO
• طرح کام، صفحه پورتال
• داشبورد پذیرش و خطا

عمده

• RFC/ADR، تاریخ غروب آفتاب و پنجره ≥90 -180 روز
• پل v1↔v2 و راهنمای مهاجرت
• دوگانه نوشتن/خواندن و آشتی دادن
• SDK با هر دو API + هشدار
• خلبان با انتگرال های کلیدی

15) برنامه پیاده سازی (3 تکرار)

1. بنیاد (2 هفته):

ثبت طرح ها، خطوط و خودکار تفاوت در CI ؛ سیاست سازگاری ؛ عنوانهای «استهلاک/غروب آفتاب».

2. نسخه های مدیریت شده (3-4 هفته):

قناری ها، پرچم های ویژگی، هشدارهای SLO ؛ پورتال نسخه ؛ SDK با پشتیبانی از 2 شاخه منتشر می شود.

3. اتوماسیون و مقیاس (مداوم):

تست های CDC از مصرف کنندگان در CI، پیش بینی غروب آفتاب در مورد روند تصویب، اعلان های خودکار و یادآوری ها.

16) مینی سوالات متداول

آیا می توانم نوع فیلد را بدون یک major تغییر دهم ؟

نه، اينطور نيست حتی «stroka → chislo» در حال شکستن است. وارد یک فیلد جدید شوید، فیلد قدیمی مستهلک می شود.

Enum: آیا می توانید ارزش ها را اضافه کنید ؟

بله، اگر مشتریان خوانندگان تحمل باشند. در غیر این صورت - اول هشدار و بتا.

چقدر باید نسخه قدیمی را نگه دارید ؟

تا کنون، پذیرش ≥95 درصد جدید حفظ شده است. مهلت را در سیاست تعیین کنید.

مجموع

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