قراردادهای تایپ‌شده بین بک‌اند و کلاینت: چرا اسکیمای مشترک باگ‌های یکپارچه‌سازی را کم می‌کند

فاصلهٔ بین «یک پاسخ نمونه که چشم توسعه‌دهنده آن را تأیید کرده» و «قراردادی که کلاینت واقعاً به آن متکی است» دقیقاً همان جایی است که بیشتر باگ‌های یکپارچه‌سازی زندگی می‌کنند. یک فیلد که در ۹۹ درصد پاسخ‌ها وجود دارد اما در یک حالت خاص (مثلاً کاربری که هنوز پروفایلش را کامل نکرده) null یا غایب است. یک عدد که بک‌اند به‌عنوان رشته برمی‌گرداند چون از یک کتابخانهٔ سریال‌سازی پیش‌فرض استفاده کرده، درحالی‌که کلاینت فرض کرده عدد است. یک آرایه که در حالت خالی، به‌جای [] مقدار null برمی‌گردد. هیچ‌کدام از این‌ها در یک تست دستی با Postman روی داده‌ٔ نمونهٔ معمول ظاهر نمی‌شوند، چون داده‌ٔ نمونه معمولاً «حالت خوب» است، نه حالت لبه‌ای.

مشکل عمیق‌تر این است که این نوع خطا معمولاً زمان اجرا خودش را نشان می‌دهد، نه زمان توسعه — دقیقاً وقتی که رفع آن گران‌ترین حالت ممکن را دارد: بعد از استقرار، وقتی کاربر واقعی به آن حالت لبه‌ای برخورد کرده. یک قرارداد تایپ‌شدهٔ مشترک، این کلاس کامل از خطاها را از دستهٔ «باگ زمان اجرا که کاربر پیدایش می‌کند» به دستهٔ «خطای زمان کامپایل که قبل از merge شدن دیده می‌شود» منتقل می‌کند. این تفاوت، تفاوت بین یک ساعت زمان توسعه و یک ساعت رفع اشکال ساعت دو نیمه‌شب است.

وقتی تیمی تصمیم می‌گیرد این مشکل را حل کند، معمولاً بین دو رویکرد انتخاب می‌کند: تایپ‌های کلاینت را دستی بنویسد و با مستندات API هماهنگ نگه دارد، یا تایپ‌ها را از یک منبع حقیقت واحد (مثلاً یک تعریف اسکیمای بک‌اند) به‌صورت خودکار تولید کند.

تایپ دستی سریع‌تر شروع می‌شود و برای یک API کوچک و پایدار کاملاً معقول است. اما هزینه‌اش با گذر زمان ظاهر می‌شود، نه در روز اول: هر تغییری در بک‌اند باید کسی به‌یاد بیاورد که باید در تایپ کلاینت هم دستی اعمال شود، و «به‌یاد آوردن» دقیقاً همان چیزی است که فرایندهای انسانی در آن ضعیف‌اند. تایپ تولیدشده این حلقهٔ یادآوری دستی را حذف می‌کند: تایپ کلاینت مستقیماً از همان تعریفی می‌آید که بک‌اند از آن پیروی می‌کند، و اگر بک‌اند تغییر کند، تولید مجدد تایپ‌ها فوراً نشان می‌دهد کجا کد کلاینت دیگر با قرارداد جدید جور درنمی‌آید — نه ماه‌ها بعد، بلکه در همان لحظه‌ای که کد تولید می‌شود یا کامپایل انجام می‌شود.

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

جایی که این بحث از یک ترجیح سبکی به یک مسئلهٔ واقعی درستی تبدیل می‌شود، مرز یک انتشار (release) است. بک‌اند و کلاینت تقریباً هرگز دقیقاً هم‌زمان مستقر نمی‌شوند — یک اپ موبایل ممکن است روزها یا هفته‌ها طول بکشد تا همهٔ کاربران آن را به‌روزرسانی کنند، درحالی‌که بک‌اند می‌تواند چند بار در روز مستقر شود. این یعنی همیشه یک پنجرهٔ زمانی وجود دارد که نسخهٔ قدیمی کلاینت با نسخهٔ جدید بک‌اند صحبت می‌کند، یا برعکس.

یک قرارداد تایپ‌شده به‌تنهایی این مسئله را حل نمی‌کند؛ فقط آن را قابل‌مشاهده می‌کند. مسئولیت واقعی روی قوانین سازگاری قرار می‌گیرد که تیم باید آگاهانه انتخاب کند: فیلد جدید اضافه‌شده باید اختیاری باشد تا کلاینت قدیمی که از وجودش خبر ندارد نشکند؛ فیلدی که دیگر استفاده نمی‌شود باید حذف نشود، بلکه به‌عنوان منسوخ علامت بخورد و برای یک دورهٔ مشخص هم‌زمان با فیلد جدید نگه داشته شود؛ و تغییر نوع یک فیلد موجود (مثلاً از رشته به عدد) تقریباً همیشه باید به‌عنوان یک فیلد کاملاً جدید مدل‌سازی شود، نه یک تغییر درجا. این‌ها قوانین نسخه‌بندی API هستند، و قرارداد تایپ‌شده فقط ابزاری است که این قوانین را قابل‌اجرا و قابل‌بررسی می‌کند — بدون آن ابزار، همین قوانین هنوز باید رعایت شوند، اما نقض‌شان تا وقتی کاربر واقعی به آن برخورد کند دیده نمی‌شود.

لایهٔ آخری که این تصویر را کامل می‌کند، تست قرارداد (contract testing) است. تست واحد معمولی بک‌اند تأیید می‌کند که منطق داخلی سرویس درست کار می‌کند؛ تست end-to-end تأیید می‌کند که کل سامانه در یک محیط شبیه‌سازی‌شده درست کار می‌کند. هیچ‌کدام از این‌ها مستقیماً این سؤال را جواب نمی‌دهد: «اگر کلاینتی که همین الان در دست کاربران است با نسخهٔ بعدی بک‌اند که قرار است مستقر شود صحبت کند، چه اتفاقی می‌افتد؟»

تست قرارداد دقیقاً همین شکاف را پر می‌کند: مصرف‌کننده (کلاینت) انتظاراتش از قرارداد را به‌صورت قابل‌اجرا مستند می‌کند، و تولیدکننده (بک‌اند) پیش از استقرار هر تغییری، این انتظارات را به‌عنوان بخشی از فرایند build خودش اجرا می‌کند. این با تایپ تولیدشده فرق دارد: تایپ‌ها تضمین می‌کنند شکل داده در زمان کامپایل درست است، اما نمی‌توانند تضمین کنند رفتار واقعی سرویس (مثلاً «این فیلد در این حالت خاص همیشه پر است») هنوز همان رفتاری است که کلاینت رویش حساب باز کرده. تست قرارداد این لایهٔ رفتاری را می‌پوشاند، جایی که تایپ به‌تنهایی نمی‌تواند.

پرسشی که تیم‌ها معمولاً دیر مطرحش می‌کنند این است: اسکیما از کجا شروع می‌شود؟ دو الگوی رایج وجود دارد. در الگوی اول، بک‌اند مالک اسکیماست — تعریف مسیرها، ورودی‌ها و خروجی‌ها در کد بک‌اند نوشته می‌شود و تایپ‌های کلاینت از روی همان تولید می‌شوند. در الگوی دوم، یک تعریف اسکیمای مستقل (یک فایل قرارداد که نه به بک‌اند تعلق دارد نه به کلاینت) منبع حقیقت است، و هم بک‌اند و هم کلاینت از روی همان تولید می‌شوند.

الگوی اول ساده‌تر است و برای تیمی که یک بک‌اند و یک یا دو کلاینت دارد کاملاً کافی است — چون فقط یک جهت تولید وجود دارد و نیازی به هماهنگی بین دو کدبیس مستقل نیست. الگوی دوم وقتی ارزشش را نشان می‌دهد که بیش از یک تیم بک‌اند وجود دارد، یا وقتی همان قرارداد باید توسط زبان‌های برنامه‌نویسی مختلف مصرف شود (مثلاً یک بک‌اند به یک زبان و چند کلاینت به زبان‌های دیگر). انتخاب اشتباه بین این دو الگو معمولاً به این شکل ظاهر می‌شود: تیمی که الگوی دوم را برای یک بک‌اند و یک کلاینت ساده انتخاب کرده، بیشتر وقتش را صرف نگه‌داشتن یک فایل قرارداد مجزا می‌کند تا صرف کاری که واقعاً برایش پول می‌گیرد.

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

نشانه‌ای که این مهاجرت درست پیش می‌رود این است که هر اندپوینت تازه تایپ‌شده، بلافاصله یک یا دو باگ قدیمی و ساکت را آشکار می‌کند — فیلدی که همیشه فرض می‌شد اجباری است اما در یک حالت خاص نبوده، یا نوعی که در مستندات یک چیز نوشته شده بود و در عمل چیز دیگری برمی‌گشت. این آشکارشدن، خودش دلیل خوبی است برای ادامه‌دادن مهاجرت به‌جای متوقف‌کردنش پس از چند اندپوینت اول.