طراحی API با Laravel برای اپ و پنل مدیریت

اگر سایت، پنل و اپ هر کدام منطق خود را داشته باشند، هر تغییر قیمت سه بار پیاده می‌شود و یکی جا می‌ماند. API همان قرارداد مشترک است. این راهنما از تحویل‌های KGSM می‌گوید چطور نسخه، احراز هویت، مستند و محدودیت نرخ را از روز اول ببندید تا اپ بعدی سامانه را نشکند.

این راهنما با عنوان «طراحی API با Laravel برای اپ و پنل مدیریت» از تجربه تحویل پروژه‌های KGSM نوشته شده: محدوده نسخه اول، انتشار مرحله‌ای، و پشتیبانی بعد از تحویل.

مخاطب، ریسک و روش KGSM

مدیر محصول یا فنی که هم پنل وب می‌خواهد هم اپ، و نگران دوباره‌کاری منطق و ناسازگاری داده است

دو پایگاه داده یعنی قیمت، موجودی و کاربر ظرف چند هفته از هم جدا می‌شوند و پشتیبانی بی‌انتها می‌شود.

KGSM یک API نسخه دار با Laravel می‌سازد تا پنل، سایت و اپ از یک منبع تغذیه شوند و تحویل مرحله‌ای بماند.

یک منبع حقیقت برای وب و اپ

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

منطق قیمت را فقط روی سرور بگذارید حتی اگر اپ آفلاین دارد. اپ فروش حضوری با دیتابیس جدا ظرف سه هفته قیمت ویترین را عقب‌تر از سایت نشان می‌داد.

نسخه، توکن و نقش

مسیر /api/v1 را از روز اول بگذارید حتی اگر فقط یک کلاینت دارید. وقتی فیلد اجباری می‌شود یا معنا عوض می‌شود، v2 را معرفی کنید و v1 را تا انتشار اجباری اپ زنده نگه دارید. توکن را کوتاه‌عمر کنید، تازه‌سازی را جدا بگذارید، و خروج را واقعاً توکن را باطل کند. نقش راننده، مشتری، صندوق و ادمین را در سرور چک کنید نه با مخفی کردن دکمه در اپ. محدودیت نرخ روی ورود و روی endpointهای حساس جلوی آزمون‌وخطای رمز را می‌گیرد. CORS را فقط برای دامنه‌های پنل باز کنید؛ ستاره باز در تولید یعنی هر سایت می‌تواند مرورگر کاربر را به API شما بزند. HTTPS اجباری است؛ توکن روی HTTP معادل کلید روی میز است. KGSM این موارد را قبل از تحویل با یک کلاینت تست واقعی — پستمن یا اپ پایلوت — رد می‌کند نه با اسلاید معماری.

تغییر اجباری فیلد آدرس بدون v2، نسخه قدیمی اپ را برای همه راننده‌ها خراب کرد. از روز اول مسیر نسخه‌دار v1 بسازید.

قرارداد با فرانت: مستند، خطا، صفحه‌بندی

تیم اپ نباید از روی حدس فیلد بسازد. یک فهرست endpoint با نمونه درخواست و پاسخ، کد خطا و معنای هر وضعیت، بخشی از تحویل است نه کار اضافه. خطای اعتبارسنجی باید فیلد به فیلد برگردد تا فرم موبایل همان لحظه ترجمه شود. صفحه‌بندی را از اول روی لیست‌های بزرگ بگذارید وگرنه اپ روی داده واقعی قفل می‌شود. فایل را از طریق URL موقت یا کنترل دسترسی بدهید، نه از پوشه عمومی حدس‌پذیر. اگر پنل وب با React یا Blade همان API را مصرف کند، باگ یک‌بار رفع می‌شود. KGSM در دموهای مرحله‌ای اول قرارداد را با یک صفحه واقعی پنل و یک صفحه لیست اپ نشان می‌دهد تا ناسازگاری زود دیده شود. ظاهر عمومی سایت را می‌توان جدا با طراحی سایت پیش برد، به شرطی که کاتالوگ از API خوانده شود نه از وردپرس موازی.

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

اشتباه دیتابیس جدا و مسیر اصلاح

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

لیست محصولات بدون صفحه‌بندی روی خط ضعیف، اپ را در ورود می‌بست. خطای اعتبارسنجی را فیلد به فیلد به کلاینت برگردانید.

لیست بدون صفحه‌بندی روی داده واقعی اپ را می‌بندد. تیم فرانت فیلد status را حدس زده بود؛ لغو سفارش در اپ با پنل یکی نبود.

همگام آفلاین بدون قفل، موجودی منفی و دو فاکتور برای یک سبد ساخت. CORS ستاره را در تولید باز نگذارید.

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

تغییر اجباری فیلد آدرس بدون v2، نسخه قدیمی اپ را برای همه راننده‌ها خراب کرد. همگام دوطرفه را بدون قفل خوش‌بینانه طراحی نکنید.

چک‌لیست اجرا

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

سناریوی واقعی 1

اپ فروش حضوری با دیتابیس جدا ظرف سه هفته قیمت ویترین را عقب‌تر از سایت نشان می‌داد.

منطق قیمت را فقط روی سرور بگذارید حتی اگر اپ آفلاین دارد.

سناریوی واقعی 2

تغییر اجباری فیلد آدرس بدون v2، نسخه قدیمی اپ را برای همه راننده‌ها خراب کرد.

از روز اول مسیر نسخه‌دار v1 بسازید.

سناریوی واقعی 3

توکن بدون انقضا روی گوشی گم‌شده، دسترسی پنل را باز گذاشت.

خروج کاربر باید توکن را باطل کند نه فقط صفحه را عوض کند.

سناریوی واقعی 4

لیست محصولات بدون صفحه‌بندی روی خط ضعیف، اپ را در ورود می‌بست.

خطای اعتبارسنجی را فیلد به فیلد به کلاینت برگردانید.

سناریوی واقعی 5

تیم فرانت فیلد status را حدس زده بود؛ لغو سفارش در اپ با پنل یکی نبود.

لیست بدون صفحه‌بندی روی داده واقعی اپ را می‌بندد.

سناریوی واقعی 6

همگام آفلاین بدون قفل، موجودی منفی و دو فاکتور برای یک سبد ساخت.

CORS ستاره را در تولید باز نگذارید.

صفحات مرتبط KGSM

ادامه را در KGSM و خدمات طراحی اپلیکیشن موبایل، برنامه‌نویسی و توسعه نرم‌افزار ببینید. مقالات مرتبط: سفارش نرم‌افزار سازمانی — چطور تیم برنامه‌نویسی انتخاب کنیم؟، تکنولوژی‌های برنامه‌نویسی برای کسب‌وکار — Laravel، React و موبایل. برای برآورد محدوده نسخه اول از فرم تماس استفاده کنید.

وقتی این نکته به تیم زنده می‌رسد باید قانون اجرایی باشد نه اسلاید: منطق قیمت را فقط روی سرور بگذارید حتی اگر اپ آفلاین دارد. برایش مالک و تاریخ بازبینی بگذارید تا در اولین هفته شلوغ فراموش نشود.

وقتی این نکته به تیم زنده می‌رسد باید قانون اجرایی باشد نه اسلاید: از روز اول مسیر نسخه‌دار v1 بسازید. برایش مالک و تاریخ بازبینی بگذارید تا در اولین هفته شلوغ فراموش نشود.

وقتی این نکته به تیم زنده می‌رسد باید قانون اجرایی باشد نه اسلاید: خروج کاربر باید توکن را باطل کند نه فقط صفحه را عوض کند. برایش مالک و تاریخ بازبینی بگذارید تا در اولین هفته شلوغ فراموش نشود.

وقتی این نکته به تیم زنده می‌رسد باید قانون اجرایی باشد نه اسلاید: خطای اعتبارسنجی را فیلد به فیلد به کلاینت برگردانید. برایش مالک و تاریخ بازبینی بگذارید تا در اولین هفته شلوغ فراموش نشود.

وقتی این نکته به تیم زنده می‌رسد باید قانون اجرایی باشد نه اسلاید: لیست بدون صفحه‌بندی روی داده واقعی اپ را می‌بندد. برایش مالک و تاریخ بازبینی بگذارید تا در اولین هفته شلوغ فراموش نشود.

وقتی این نکته به تیم زنده می‌رسد باید قانون اجرایی باشد نه اسلاید: CORS ستاره را در تولید باز نگذارید. برایش مالک و تاریخ بازبینی بگذارید تا در اولین هفته شلوغ فراموش نشود.

وقتی این نکته به تیم زنده می‌رسد باید قانون اجرایی باشد نه اسلاید: یک شناسه درخواست در لاگ، دیباگ موبایل را نصف می‌کند. برایش مالک و تاریخ بازبینی بگذارید تا در اولین هفته شلوغ فراموش نشود.

وقتی این نکته به تیم زنده می‌رسد باید قانون اجرایی باشد نه اسلاید: همگام دوطرفه را بدون قفل خوش‌بینانه طراحی نکنید. برایش مالک و تاریخ بازبینی بگذارید تا در اولین هفته شلوغ فراموش نشود.

وقتی این نکته به تیم زنده می‌رسد باید قانون اجرایی باشد نه اسلاید: اپ فروش حضوری با دیتابیس جدا ظرف سه هفته قیمت ویترین را عقب‌تر از سایت نشان می‌داد. برایش مالک و تاریخ بازبینی بگذارید تا در اولین هفته شلوغ فراموش نشود.