هر API که بیشتر از یک فصل زنده بماند تغییر میکند. نسخهبندی خوب اجازه میدهد قابلیتهای جدید بدهید و مشتریهای فعلی را نشکنید. این یک راهنمای میدانی با تمرکز روی سادگی و ایمنی است.
اصول
- اول سازگاری: تغییر شکستنآور آخرین گزینه است.
- تکامل قابل پیشبینی: قوانین deprecate و حذف را مستند کنید.
- نسخه صریح: نسخه را در URL یا هدر شفاف کنید.
سبکهای نسخهبندی
- نسخه در URL (
/v1/): شفاف و cache-friendly؛ پیشفرض خوب برای HTTP. - نسخه در هدر (
Accept: application/vnd.acme+json; version=2): URL ثابت میماند؛ برای API عمومی با media type خوب است. - نسخه میدان به میدان: فیلد جدید اضافه کنید و پیشفرض بگذارید؛ اغلب نیاز به major جدید را کم میکند.
کی major جدید بدهیم؟
- حذف/تغییر نام فیلد یا مسیر.
- تغییر پارامترهای اجباری یا معنا.
- تغییر مدل نمایش (مثلاً pagination یا auth).
اگر مجبور به شکستن هستید، v1 و v2 را همزمان با پنجره مهاجرت نگه دارید و مصرف v1 را مانیتور کنید.
بازی سازگار با عقب
- فقط اضافه کنید؛ معنای فیلدهای قدیمی را عوض نکنید.
- فیلدهای منسوخ را در اسکیما علامت بزنید و هدر
Deprecationبفرستید. - پارامتر جدید را قابل پیشفرض کنید، نه اجباری.
- رفتارهای جدید را پشت feature flag فعال کنید تا قبل از freeze تست شود.
حاکمیت مقیاسپذیر
- برای هر تصمیم breaking یک ADR ثبت کنید.
- قبل از حذف نسخه قدیم، تست قرارداد از مصرفکنندهها بگیرید.
- مصرف نسخهها را per-client بسنجید و تاریخ حذف را در ریلیز نوت بنویسید.
- سازگاری OpenAPI/Proto را lint و CI کنید (
buf breaking,vacuum).
کیت مهاجرت برای مشتریها
- changelog و نمونه diff بین نسخهها بدهید.
- SDK یا کلاینت تایپشده عرضه کنید تا لبههای breaking نرم شود.
- محیط sandbox و ابزار replay فراهم کنید تا سریع اعتبارسنجی کنند.
چکلیست قبل از انتشار نسخه بعد
- مسیریابی نسخه در staging با replay ترافیک واقعی تست شده.
- مانیتورینگ per-version (rate، خطا، تأخیر).
- هدر Deprecation حداقل یک چرخه انتشار کلاینت فعال بوده.
- پلن rollback: نسخه قبلی داغ و دادهسازگار باقی میماند.
نسخهبندی را مثل محصول ببینید: مستند، اندازهگیریشده و پشتیبانیشده؛ اینگونه سرعت تیم حفظ میشود و مشتریها جا نمیمانند.
ادامه مطالعه