بازخورد حلقه API و تکامل نسخه

1) چرا شما نیاز به یک حلقه بازخورد مدیریت شده دارید

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

2) کانال های بازخورد (و وزن آنها)

تله متری استفاده (در زمینه نقاط پایانی/پارامترها/خطاها) منبع اصلی حقیقت است.
RFC ها از مشتریان/تیم های داخلی - پیشنهادات ساختاری.
نظرسنجی NPS/DevEx و «مصاحبه انتگرال» بازخورد با کیفیت بالا هستند.
مسائل/انجمن/پورتال - زنگ سریع مشکلات.
Support/Slack - موارد حادثه ای که در معیارها قابل مشاهده نیستند.

3) معماری حلقه بازخورد (جریان داده ها)

Producers (SDK/gateway/portal) → Usage & Error Bus → DWH/Lake → Auto-Dif/Lint → داشبورد و هشدارها → نقشه راه/عقب ماندگی.

• مجموعه: شمارنده تماس، پارامترها، هدر نسخه، کدهای خطا، تاخیر.
• تجزیه و تحلیل: روند پذیرش، زمینه های مرده، 4xx/5xx مکرر، همبستگی با انتشار.
• کنترل قرارداد: schema-diff، CDC (قراردادهای مبتنی بر مصرف کننده)، API linter.
• فرمانداری: RFC/ADR، شورای انتشار، تقویم نسخه ها و کاهش.

4) سیاست نسخه (SemVer + کانال)

SemVer برای SDK/مشتریان: 'MAJOR. جزئی است. پچ.
نسخه های API: 'v1'، 'v2' (شکستن - فقط عمده). جزئی - اضافه کردن زمینه های سازگار/نقاط پایانی.
کانال های عرضه: «تجربی» → «بتا» → «GA» → «منسوخ» → «غروب آفتاب».

جایی که برای ذخیره نسخه

مسیر نشانی وب: "/v1/... '- قابل فهم و ذخیره سازی.

عنوان: «X-API-Version: 2025-11-03» - برای قراردادهای «تاریخ»

محتوا مذاکره: 'پذیرش: نرم افزار/VND. ACME. v1 + json '- دانه بندی خوب.
یک روش اصلی را انتخاب کنید، بقیه سازگاری/مهاجرت است.

5) سازگاری و «حق اضافه کردن»

• فیلدها/مقادیر اختیاری را اضافه کنید (اگر مشتریان خواننده تحمل پذیر باشند).
• نقاط پایانی جدید/پارامترهای کوئری با معانی پیش فرض.
• افزایش محدودیت/اندازه (در حالی که صرفه جویی در قرارداد).

• تغییر نام/حذف فیلدها، تغییر انواع/فرمت ها.
• تغییر اجباری، معانی خطاها/وضعیت ها.
• تغییرات پیش فرض که منطق مشتری را تحت تاثیر قرار می دهد.

قانون: جادوی کمتر، صریح تر (نسخه های جدید به جای فیلدهای «دوباره تعریف شده»).

6) فرآیند RFC/ADR (خلاصه شده)

1. ابتکار عمل (RFC) - انگیزه، موارد استفاده، نفوذ، جایگزین ها.
2. ارزیابی (بررسی قوس) - ایمنی، سازگاری، SLO، finops.
3. ADR - تصمیم گیری با عواقب ساخته شده است.
4. یخ طراحی - نمونه اولیه/ROS، تست قرارداد.
5. پیاده سازی - پرچم های ویژگی، کانال قناری/بتا، قابلیت مشاهده.
6. GA - مستندات/SDK/مهاجرت، SLO، پشتیبانی.
7. رد/غروب آفتاب - طرح خروج، سیگنال های ماشین، اعتبارات SLA برای اشتباهات.

yaml rfc: RFC-0027 title: "Reports v2 cursor pagination"
motivation: "Offset causes drift at high churn"
breaking_change: false rollout: ["beta", "region=eu-west-1", "10% tenants"]
metrics: ["adoption_rate", "error_rate{status=422,429,5xx}", "latency_p95"]
migration: "v1=read-only 90d; dual-write v1/v2 30d"

7) مدارها و خودکار تفاوت (OpenAPI/AsyncAPI/Proto)

منبع واحد: طرح های موجود در مخزن (رجیستری monorepo یا versioned).
روابط عمومی Auto-diff → پرچم «خراب می شود/خراب نمی شود» ؛ مسدود کردن دروازه برای تغییرات ناسازگار.
Linter: نام/نوع, stable 'error _ code', checkup pagination/idempotency.

CDC: قراردادهای مصرف کننده (آزمون مصرف کننده) - ورود به CI ؛ دکمه قرمز نقض حقوق بشر

yaml
- name: API Schema Diff run: api-diff --from main --to PR --fail-on=breaking --report artifact. json

8) بتا، قناری، پرچم های ویژگی

بتا: انتخاب در مستاجران/کلید، محدودیت RPS/جغرافیایی.
Canary: توسط٪ ترافیک یا لیست مشتریان، بازگشت خودکار بر روی سیگنال های SLO (خطاها/تاخیر/429).
پرچم ویژگی: را قادر می سازد/غیر فعال رفتار استقرار رایگان ؛ در سرویس پیکربندی ذخیره کنید، حسابرسی را وارد کنید.

9) تخفیف و غروب آفتاب

اطلاعیه: changelog + پورتال، استهلاک وب سایت. توجه داشته باشید "، عنوان" تخفیف: درست ".
پنجره: حداقل 90-180 روز (بستگی به بحرانی).
نکات: در پاسخ 'لینک: <...> ؛ rel = "deprecation" "и" Rel: "successor-version" ".
قابلیت مشاهده: داشبورد «چه کس دیگری در v1 ؟ «، اطلاعیه خودکار نامه/پورتال.
غروب آفتاب: عنوان «غروب آفتاب: 2026-03-31T00: 00: 00Z», پس از مهلت, 410 رفته برمی گردد.

json
{
"type": "deprecation. notice",
"api": "reports. v1",
"sunset_at": "2026-03-31T00:00:00Z",
"migrate_to": "reports. v2",
"guides": ["reports-v2-migration"],
"contact": "support@example. com"
}

10) مهاجرت و همزیستی نسخه ها

خواندن دوگانه/نوشتن دوگانه برای مدت زمان حرکت ؛ سازگاری باید در برابر گزارش ها بررسی شود.
آداپتورهای (نازک) برای مشتریان قدیمی تنها یک اقدام موقت هستند.
راهنماهای مهاجرت: نقشه زمینه، نمونه هایی از درخواست ها، تله های مکرر.
SDK: با پشتیبانی از هر دو نسخه و «هشدارهای انحراف» (1 بار در هر فرآیند) منتشر می شود.
نیمکت تست: sandbox v2، رفع/ژنراتور داده.

11) معیارهای موفقیت تکامل

نرخ پذیرش v2:٪ از ترافیک/مشتریان در نسخه جدید.
زمان-به-اتخاذ: متوسط زمان مهاجرت.
حوادث کامپات عقب: شماره شکست.
مخلوط خطا: سهم 4xx/5xx پس از انتشار، خوشه 422/429.
DevEx: زمان NPS/» اولین درخواست موفقیت آمیز«.
هزینه برای خدمت: هزینه زیرساخت در هر تماس/گزارش.

12) تغییر مدیریت و هشدارها

Pre-GA SLO: آستانه جداگانه برای بتا/قناری ؛ قوانین سوختن سریع و آهسته

هشدارها: سنبله 5xx/latency، 422/429 افزایش نقاط پایانی جدید، افت پذیرش.
انجماد آزاد در طول احتراق بودجه خطا.

13) مستندات، پورتال، ارتباطات

Changelog с датами (اضافه/تغییر/مستهلک/حذف/ثابت).
راهنماها: مهاجرت، نمونه ها، «چک لیست به روز رسانی».
پورتال: کارت نسخه سرویس، وضعیت، تاریخ غروب آفتاب، جعبه شن و ماسه API v2، دکمه «درخواست دسترسی».
بسته Comm: نامه های پستی، RSS، آگهی ها در پورتال، یادداشت های انتشار SDK.

14) سیاست نسخه نمونه (گزیده ای)

yaml versioning:
strategy: "path"   # path    header    media compatibility:
minor: "additive-only"
patch: "bugfix/perf/no schema change"
deprecation:
min_notice_days: 120 comms: ["portal", "email", "status-webhook"]
rollout:
stages: ["exp", "beta", "ga"]
canary_policy:
step: [10,25,50,100]
checks: ["5xx_rate","p95_latency","429_rate","adoption"]

15) قراردادهای مصرف کننده محور (CDC)

ارائه دهنده طرح و نمونه ها را منتشر می کند.
مصرف کننده انتظارات (پیمان/hoverfly) را که در CI تامین کننده معتبر است، ذخیره می کند.
قانون: شما نمی توانید نسخه ای را منتشر کنید که حداقل یک مصرف کننده امضا شده را بشکند (اگر پنجره مهاجرت برآورده نشده و توافق نشده باشد).

16) ضد الگوهای

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

17) فهرست جدید MINOR/MAJOR شماره

• RFCs/ADRs تایید شده ؛ ایمنی/finops/مشاهده پذیری ارزیابی شده است.
• طرح های در ثبت نام ؛ تیرک ها سبز هستند ؛ خودکار تفاوت نشان می دهد شکستن (برای MINOR).
• پرچم های بتا ؛ نقشه قناری ؛ بازگشت خودکار по SLO
• مستندات/SDK/نمونه های به روز شده ؛ راهنمای مهاجرت آماده است.
• پورتال: کارت نسخه، بنر کاهش/دسترسی.
• طرح Comm (لیست پستی، وب سایت های وضعیت) و تاریخ غروب آفتاب.
• داشبورد پذیرش/خطا ؛ هشدارها ایجاد شده است.
• شرایط حقوقی/قراردادی (اگر SLA/صدور صورت حساب تغییر).

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

تکرار 1 - بنیاد (2 هفته)

فعال کردن استفاده/خطا تله متری توسط endpoints و نسخه.
ایجاد طرح در رجیستری، پیکربندی پرز و خودکار تفاوت در CI.
تعریف سیاست نسخه و کاهش ؛ انتشار به پورتال.

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

پیاده سازی فرآیند RFC/ADR، canary/beta با پرچم های ویژگی و بازگشت خودکار.
CDC مصرف کنندگان کلیدی را در ارائه دهنده CI آزمایش می کند.

پذیرش داشبورد/خطاها، قالب های comm و افسردگی webhooks. توجه کنید"

تکرار 3 - مقیاس و اتوماسیون (مداوم)

تولید خودکار SDK/اسکله از نمودارها ؛ قطار را آزاد کنید

sandbox چند نسخه ؛ نوشتن دوگانه برای مهاجرت

پیش بینی تاریخ غروب آفتاب با روند تصویب ؛ یادآوری خودکار

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

آیا من همیشه نیاز به ضربه عمده برای هر گونه ناراحتی ؟

نه، اينطور نيست اگر تغییرات افزودنی هستند و مشتریان موجود را شکستن نیست - MINOR. فقط برای عدم تطابق.

نسخه تاریخ یا «v2» ؟

'v2' برای اسناد و حافظه های پنهان ساده تر است. هدرهای تاریخ دار برای ناسازگاری های «نرم» و A/B مناسب هستند.

چگونه بفهمیم که وقت بستن v1 است ؟

تصویب v2> 95٪، هیچ مشتری بحرانی در v1، پنجره کاهش پایدار است، پشتیبانی خطاها/v1 → حداقل است.

مجموع

یک API قوی تکامل می یابد قابل پیش بینی: تله متری و CDC گرفتن خطرات، RFC/ADRs ارائه راه حل های شفاف، قناری/بتا کاهش هزینه خطا، و یک نسخه روشن و سیاست کاهش باعث می شود تغییرات برای مشتریان امن است. ثابت یک منبع واحد از مدارهای، به طور خودکار تفاوت/پرز و ارتباطات، اندازه گیری تصویب - و نسخه های خود را متوقف خواهد شد «شکستن» انتگرال، و سرعت توسعه محصول افزایش خواهد یافت.