ترتیب ساخت محصول؛ اول قرارداد API، بعد UI پنل و اپ
ساخت UI قبل از تثبیت قرارداد API معمولاً به صفحات زیبا و backend شکننده ختم میشود. ترتیب درست: اول قرارداد و endpoint، بعد پنل و اپ.
فهرست سریع
در پروژههای پنل و اپ، یک وسوسهٔ رایج وجود دارد: اول صفحات را بسازیم تا ذینفع ببیند «چیزی ساخته شده». تا وقتی فقط ماکت است، مشکلی نیست؛ اما وقتی تیم شروع به کدنویسی UI میکند و قرارداد API هنوز ثابت نشده، هر جلسهٔ نمایش به لیست تغییر endpoint، فیلد گمشده و دوبارهکاری در فرانت تبدیل میشود.
این مقاله دربارهٔ ترتیب ساخت محصول است—نه اصول طراحی API. میپرسد چرا در وباپ اختصاصی، قرارداد API و endpointها باید قبل از UI پنل و اپ جلو بیفتند. اگر به اصول طراحی API و یکپارچهسازی نیاز دارید، مقاله طراحی API و وبسرویس زاویهٔ فنی عمیقتر را پوشش میدهد. در همرانیک ترتیب ساخت را با جریان کار واقعی تیم هماهنگ میکنیم، نه با مد فقط-نمایشی.
مرز مهم مقاله
این متن راهنمای «API-first به هر قیمت» یا حذف طراحی UI نیست. تمرکز روی ترتیب ساخت است: چه زمانی UI قبل از قرارداد API هزینهٔ پنهان میسازد و چطور ترتیب درست، سرعت واقعی تیم را بالا میبرد.
وقتی UI جلو میزند، چه اتفاقی میافتد؟
تیم فرانت صفحهٔ لیست سفارش را با ستونها و فیلترهایی میسازد که در جلسهٔ اول خوشآیند بود. بکاند هنوز نمیداند وضعیت «در انتظار تأیید مالی» جدا از «در انتظار انبار» است یا نه. نتیجه: endpoint موقت، فیلد اضافهشده در آخر هفته، و refactor صفحهای که «تمام شده» بهنظر میرسید.
این الگو فقط در استارتاپهای بیتجربه نیست. حتی تیمهای حرفهای وقتی فشار «تحویل دمو» بالا باشد، UI را جلو میاندازند. هزینهٔ پنهان در جلسات هماهنگی، باگهای «روی سیستم من کار میکند»، و تأخیر در اتصال اپ موبایل بعداً جمع میشود. مقاله طراحی پنل مدیریتی اختصاصی دربارهٔ UX پنل است؛ اینجا سؤال این است که آن UX روی چه قراردادی سوار میشود.
چرا اول قرارداد API، نه صرفاً «اول بکاند»؟
«اول بکاند» گاهی به معنای نوشتن کد دیتابیس بدون توافق روی payload و خطاهاست. منظور از API-first در اینجا قرارداد است: چه resourceهایی، چه فیلدهایی، چه status codeها، چه pagination، و چه قوانین دسترسی—قبل از اینکه یک کامپوننت Vue یا Blade به endpoint وصل شود.
۱. یک منبع حقیقت برای پنل و اپ
همان endpoint، دو کلاینت
پنل مدیر و اپ موبایل اپراتور باید از یک قرارداد تغذیه شوند. اگر UI پنل جلو بیفتد، اپ بعداً با endpoint متفاوت یا فیلدهای ناقص مواجه میشود.
۲. کاهش rework فرانت
صفحه روی دادهٔ واقعی طراحی میشود
وقتی قرارداد ثبت سفارش، پیوست، تاریخچه وضعیت و خطاهای اعتبارسنجی نوشته شده باشد، UI یکبار درست ساخته میشود—نه سه بار بعد از هر کشف backend.
۳. موازیسازی امن تیم
فرانت و بک همزمان جلو میروند
با OpenAPI یا mock از قرارداد، تیم UI میتواند موازی کار کند بدون حدس زدن response. این سرعت واقعی است، نه ساخت صفحهٔ جدا از واقعیت API.
۴. تست و پذیرش شفاف
معیار «تمام شد» قابل امضا است
وقتی قرارداد قبل از UI باشد، تست پذیرش میتواند بگوید «POST /orders با payload X باید 201 بدهد»—نه «صفحه باید شبیه فیگما باشد ولی ذخیره نشود».
ترتیب عملی ساخت: از جریان کار تا UI
ترتیب پیشنهادی برای پنل و اپ عملیاتی: (۱) جریان کار و نقشها—چه کسی چه کاری میکند؛ (۲) مدل داده و وضعیتها؛ (۳) قرارداد API (endpoint، schema، خطاها)؛ (۴) mock یا stub برای توسعهٔ موازی؛ (۵) UI پنل و اپ روی همان قرارداد؛ (۶) یکپارچهسازی و تست end-to-end.
این ترتیب با تعریف MVP نرمافزار اختصاصی همراستاست: MVP یعنی کمترین مسیر قابل تحویل، نه کمترین صفحهٔ قابل کلیک. اگر از Laravel و Vue استفاده میکنید، مقاله توسعه با Laravel و Vue نشان میدهد API و پنل چطور در یک محصول کنار هم مینشینند—با فرض اینکه ترتیب رعایت شده باشد.
استثناء: وقتی هدف فقط اعتبارسنجی UX با کاربر نهایی است، prototype بدون backend منطقی است—به شرطی که بهعنوان ماکت برچسب بخورد و وارد اسپرینت تولید نشود.
چکلیست: آیا ترتیب ساخت درست است؟
- جریان کار و نقشها قبل از endpoint نوشته شدهاند؟
- schema پاسخ JSON برای هر endpoint اصلی تعریف شده؟
- خطاهای اعتبارسنجی و status code در قرارداد آمدهاند؟
- پنل و اپ موبایل از یک قرارداد مشترک تغذیه میشوند؟
- mock یا OpenAPI برای توسعهٔ موازی فرانت موجود است؟
- صفحهٔ UI بدون endpoint نهایی «تمامشده» اعلام نشده؟
- تست پذیرش بر اساس قرارداد API قابل اجرا است؟
- تغییر قرارداد بعد از UI، فرایند version/review دارد؟
جمعبندی: UI زیبا بدون قرارداد، محصول پایدار نمیسازد
ترتیب ساخت محصول—اول قرارداد API، بعد UI پنل و اپ—راهی برای تحویل سریعتر و پایدارتر است. وقتی endpoint و payload ثابت باشند، تیم کمتر بین جلسهٔ نمایش و refactor گیر میکند و مسیر اتصال اپ موبایل از اول روشن میماند.
اگر پروژهٔ شما در میانهٔ راه UI-first گیر کرده، بهتر است یک بازنگری کوتاه روی قرارداد API قبل از sprint بعدی بگذارید. همان بازنگری معمولاً هزینهٔ هفتههای بعد را کم میکند.
برای ترتیب ساخت پروژه، قرارداد را با هم ببندیم
اگر پنل و اپ شما با تغییر مکرر endpoint یا rework فرانت مواجه است، در همرانیک اول جریان کار و قرارداد API را شفاف میکنیم—بعد UI را روی پایهٔ درست میسازیم.
پرسشهای پرتکرار
آیا API-first یعنی هیچ UI تا آخر sprint نسازیم؟
نه. منظور این است قرارداد API قبل از کد UI تولیدی ثبت شود. میتوانید با mock موازی کار کنید؛ اما endpoint و schema باید توافقشده باشند، نه حدسی.
تفاوت این مقاله با طراحی API چیست؟
مقالهٔ طراحی API دربارهٔ اصول امنیت، مستندسازی و مقیاس API است. این متن دربارهٔ ترتیب ساخت در پروژه است: چرا UI نباید قبل از قرارداد جلو بیفتد.
اگر UI از قبل ساخته شده چه کنیم؟
قرارداد API را از روی جریان کار واقعی بنویسید، gapها را لیست کنید، و refactor برنامهریزیشده انجام دهید. بدون قرارداد، هر feature جدید همان rework را تکرار میکند.
برای MVP هم باید API-first باشیم؟
بله، در مقیاس MVP. MVP کوچکترین مسیر تحویل است؛ قرارداد API همان مسیر را برای پنل و اپ قابل اتکا میکند.