۱. نام پروژه را تعیین کنید
سازنده را باز کنید و نام روشنی مانند inventory_api انتخاب کنید. یک نسخه پشتیبانی‌شده پایتون انتخاب کنید و نام بسته را ساده نگه دارید؛ استفاده از حروف، رقم و زیرخط معمولاً آسان‌تر است.
راهنمای عملی برای تعریف پیکربندی، تولید، بررسی و استفاده از پروژه‌های بک‌اند FastAPI با API Besaz.
API Besaz یک تولیدکننده بک‌اند مبتنی بر پیکربندی است. پیکربندی شما شامل تنظیمات پروژه، پایگاه داده، موجودیت‌ها، APIها، امنیت، وظایف پس‌زمینه، مشاهده‌پذیری، تست‌ها و در صورت نیاز استقرار است. موتور این تعریف را اعتبارسنجی می‌کند و فایل‌های متناسب با گزینه‌های فعال را از قالب‌ها تولید می‌کند. خروجی یک پروژه بک‌اند قابل‌دانلود است؛ نه یک جایگزین برای همه مراحل ساخت محصول.
این راهنما نشان می‌دهد انتخاب‌های سازنده چگونه به هم مرتبط می‌شوند. انبارداری فقط یک مثال است؛ نام‌ها و فیلدها را متناسب با برنامه خود انتخاب کنید.
سازنده را باز کنید و نام روشنی مانند inventory_api انتخاب کنید. یک نسخه پشتیبانی‌شده پایتون انتخاب کنید و نام بسته را ساده نگه دارید؛ استفاده از حروف، رقم و زیرخط معمولاً آسان‌تر است.
موجودیت Category را با فیلدهای id و name بسازید. سپس Product را با id، name، price از نوع decimal و stock از نوع integer بسازید. فقط فیلدهای لازم را اضافه کنید و پیش از ادامه، اجباری‌بودن، مقدار پیش‌فرض و محدودیت‌های کمینه/بیشینه را بررسی کنید.
اگر هر محصول به یک دسته تعلق دارد، رابطه many_to_one را از Product به Category تعریف کنید. جهت رابطه را با دقت بخوانید؛ جهت اشتباه ممکن است مدل داده‌ای معتبر اما متفاوت با نیاز شما ایجاد کند.
برای products و categories مسیرهای مجموعه REST تعریف و متدهای HTTP لازم را انتخاب کنید. مسیر مجموعه را دستی با /{id} تمام نکنید؛ موتور بر اساس قواعد تولید، مسیرهای رکورد تکی را اضافه می‌کند. خلاصه نهایی مسیرها را پیش از تولید بررسی کنید.
احراز هویت، مدیریت، کش، WebSocket، GraphQL، وظایف پس‌زمینه، تست‌ها، مشاهده‌پذیری یا فایل‌های Docker را فقط در صورت نیاز فعال کنید. بعضی گزینه‌ها به ماژول‌های دیگر وابسته‌اند؛ پیام اعتبارسنجی را برطرف کنید و آن را دور نزنید.
همه پیام‌های اعتبارسنجی را رفع کنید، هزینه نهایی توکن محاسبه‌شده در سرور را بررسی و تولید را ثبت کنید. پس از تکمیل کار، ZIP را دانلود و استخراج کنید. ابتدا README و نمونه تنظیمات محیطی را بخوانید؛ سپس مهاجرت‌ها، مسیرها و تست‌ها را پیش از اتصال سرویس‌های واقعی یا استقرار بررسی کنید.
فایل‌های دقیق به پیکربندی شما بستگی دارند. خروجی معمولاً شامل بسته برنامه و فایل‌های وابستگی و تنظیمات است؛ قابلیت‌های انتخاب‌شده ممکن است احراز هویت، مهاجرت، تست و دارایی‌های استقرار را اضافه کنند. API Besaz کد بک‌اند تولید می‌کند، نه فرانت‌اند کامل و کاربرمحور برنامه شما.
این ابزارها لزوماً جایگزین هم نیستند؛ ترکیب مناسب به مسئله شما بستگی دارد. API Besaz روی تعریف و تولید لایه بک‌اند تمرکز دارد.
برای تحقیق، پیشنهاد معماری، نوشتن یا تغییر کد، عیب‌یابی و خودکارسازی کارهای توسعه مفیدند. خروجی Agent را همچنان باید بازبینی و آزمایش کرد.
برای ساخت رابط کاربری، فرم‌ها، اپ‌های داخلی و جریان‌های کاری سریع‌اند. وقتی محصول به بک‌اند سفارشی یا API مستقل نیاز دارد، می‌توانند از API تولیدشده استفاده کنند.
به شما اجازه می‌دهد مدل داده، رابطه‌ها، مسیرها و ماژول‌های بک‌اند را به شکل پیکربندی روشن تعریف کنید و یک پروژه FastAPI قابل‌دانلود بگیرید.
تنظیمات زیر به موتور تولید داده می‌شود. دسترس‌پذیری برخی گزینه‌ها به وابستگی‌های تعریف‌شده در مدل پیکربندی بستگی دارد:
هزینه نهایی را در پنل هزینه توکن پیش از تولید بررسی کنید. هزینه به گزینه‌های فعال و تعداد موجودیت‌ها بستگی دارد؛ برآورد سمت کاربر صرفاً نمایشی است و سرور هزینه را دوباره محاسبه می‌کند.
هر موجودیت از فیلدهای نوع‌دار تشکیل می‌شود. موتور بر اساس نوع فیلد، گزینه‌ها و محدودیت‌های پشتیبانی‌شده را اعتبارسنجی می‌کند؛ محدودیت‌های دقیق را در سازنده بررسی کنید.
| نوع | نوع پایتون | محدودیت‌ها |
|---|---|---|
| string | str | min_length, max_length, pattern |
| text | str | min_length, max_length, pattern |
| integer | int | min_value, max_value |
| float | float | min_value, max_value |
| decimal | Decimal | min_value, max_value |
| boolean | bool | — |
| date | date | — |
| datetime | datetime | — |
| uuid | UUID | — |
| enum | Enum | choices (required) |
| json | dict | — |
رابطه‌های موجودیت‌ها در پیکربندی تعریف می‌شوند. موتور بر اساس نوع رابطه، کلید خارجی یا جدول واسط می‌سازد و موارد ناسازگار را اعتبارسنجی می‌کند.
| نوع | معنا | مثال |
|---|---|---|
| many_to_one | چند رکورد به یک رکورد اصلی | چند سفارش برای یک مشتری |
| one_to_many | یک رکورد اصلی به چند رکورد وابسته | یک مشتری با چند سفارش |
| many_to_many | چندبه‌چند (با جدول واسط) | مطلب‌ها و برچسب‌ها |
| one_to_one | یک‌به‌یک | کاربر و نمایهٔ او |
برای endpointهای REST، موجودیت، مسیر مجموعه و متدهای مجاز را در پیکربندی انتخاب کنید. موتور مسیرهای مربوط به عملیات تکی را مطابق قواعد تولید اضافه می‌کند.
get, post, put, patch, delete{id} تعریف کنید — API Besaz مسیر /{id} را برای عملیات تکی خودکار اضافه می‌کند.روترها و عملیات API را از روی endpointها و موجودیت‌های تعریف‌شده تولید می‌کند؛ REST در مدل پیکربندی به‌صورت پیش‌فرض فعال است.
در صورت فعال‌بودن، اجزای احراز هویت JWT، مدیریت نشست و TOTP تولید می‌شوند. احراز هویت به REST و تنظیم GeoIP نیاز دارد.
پنل SQLAdmin اختیاری است و طبق اعتبارسنجی موتور فقط وقتی قابل استفاده است که احراز هویت نیز فعال باشد.
در صورت فعال‌بودن و انتخاب Strawberry، schema و resolverهای GraphQL در کنار APIهای دیگر تولید می‌شوند؛ این قابلیت به احراز هویت نیاز دارد.
اتصال بلادرنگ اختیاری است. وقتی احراز هویت فعال باشد، اتصال از سازوکار بلیت یک‌بارمصرف استفاده می‌کند؛ در حالت بدون احراز هویت، اتصال ناشناس است.
کش به‌صورت اختیاری قابل فعال‌سازی است. تولیدشده برای اتصال به Redis تنظیم می‌شود و در محیط اجرا به سرویس Redis قابل دسترس نیاز دارد.
در صورت فعال‌بودن، کد اتصال به RabbitMQ و اجزای لازم برای پیام‌رسانی/وظایف پس‌زمینه ایجاد می‌شود.
تنظیمات ثبت رویداد و متریک‌ها را مطابق پیکربندی تولید می‌کند. داشبوردها و سرویس‌های مکمل به تنظیمات استقرار وابسته‌اند.
فایل‌های Docker و Compose و پیکربندی Nginx فقط در صورت فعال‌بودن گزینه استقرار تولید می‌شوند؛ برای انتشار عمومی، TLS را نیز در لایه استقرار تنظیم کنید.
تست‌های pytest بر اساس موجودیت‌ها، endpointها و ماژول‌های فعال ساخته می‌شوند. تولید فایل‌های Locust مستقل از pytest است؛ تعداد تست‌ها به تعریف هر پروژه بستگی دارد.
امنیت و نگهداشت‌پذیری بخشی از فرایند اصلی API Besaz هستند. اعتبارسنجی پیکربندی، schemaهای نوع‌دار، قواعد مالکیت و فیلدهای قابل‌نوشتن در Blueprint، تست‌های تولیدشده و راهنمای استقرار، یک پایه بک‌اند قابل‌بررسی و قابل‌توسعه در اختیارتان می‌گذارند. این پلتفرم با ابزارهای شناخته‌شده امنیتی و آزمون‌های دستی ارزیابی شده است؛ بنابراین می‌توانید توسعه را از یک نقطه شروع آزموده و ساختارمند ادامه دهید، نه از یک اسکلت خالی.
موتور پیش از تولید، پیکربندی پروژه را اعتبارسنجی می‌کند. برای منابعی که در Blueprint تعریف می‌شوند، می‌توان schemaها و محدودیت‌های نوع‌دار، کنترل مالکیت هر کاربر، قواعد دسترسی مبتنی بر نقش و محدودیت فیلدهای قابل‌تغییر را تولید کرد. اگر مالکیت، نقش‌ها و فیلدهای قابل‌نوشتن را درست تعریف کنید، این کنترل‌ها برای مهار مسیرهای متداول IDOR و Mass Assignment در endpointهای تولیدشده طراحی شده‌اند. در دفاع چندلایه، این سازوکارها یکدیگر را تقویت می‌کنند؛ اما مسیرهای سفارشی، تغییر منطق مجوزدهی یا پیکربندی نادرست همچنان باید بازبینی شوند.
API Besaz با CodeQL برای تحلیل ایستا، OWASP ZAP برای اسکن وب و API و OpenVAS برای ارزیابی زیرساخت آزمایش شده و آزمون‌های امنیتی دستی نیز روی آن انجام شده‌اند. یافته‌های گزارش‌شده ابزارها بررسی شدند و در محدوده نسخه و پیکربندی آزموده‌شده، مثبت کاذب ارزیابی شدند؛ پس از این بازبینی، نسخه بررسی‌شده آزمون‌های مربوط را با نتیجه قابل‌قبول پشت سر گذاشته است. این موضوع شاهد معناداری از آزمون نسخه و پیکربندی مشخص است، نه تضمینی برای بی‌نقص‌بودن هر کد سفارشی که بعداً به پروژه اضافه می‌شود.
آزمون‌های دستی، IDOR یا دسترسی غیرمجاز به رکورد و نیز Mass Assignment را پوشش داده‌اند. گزارش داخلی موجود ۲۹ مورد آزمون موفق، صفر شکست و دو مورد نامرتبط با رفتار برنامه را ثبت می‌کند؛ دو مورد آخر به‌دلیل ناهماهنگی درخواست آزمون یا مسیر با route مربوط بوده‌اند. برای منابع تعریف‌شده در Blueprint، قواعد مالکیتِ درست تنظیم‌شده دسترسی به رکوردها را محدود می‌کنند و schemaها و سازوکار محافظت از فیلدها، مقادیری را که کاربر می‌تواند تعیین یا تغییر دهد محدود می‌کنند. این حفاظت درباره routeها و پیکربندی آزموده‌شده است؛ endpointهای سفارشی و قواعد کسب‌وکار به آزمون جداگانه مجوزدهی و اعتبارسنجی ورودی نیاز دارند.
در آزمون بار، پلتفرم در محیط آزموده‌شده به نرخ حداکثر ۲٬۵۰۰ درخواست در ثانیه رسیده است. در صورت فعال‌کردن گزینه مربوط، امکان ساخت سناریوهای Locust برای پروژه تولیدشده نیز وجود دارد. این نتیجه توان عملیاتی مفیدی را در همان بارکاری و محیط نشان می‌دهد؛ ظرفیت واقعی به رفتار endpointها، پرس‌وجوهای پایگاه داده، سخت‌افزار، تعداد worker یا replica، شبکه و پیکربندی بستگی دارد. پیش از انتشار، نرخ درخواست را همراه با زمان پاسخ P50/P95/P99 و نرخ خطا، زیر بارکاری واقعی خودتان اندازه‌گیری کنید.
بک‌اند تولیدشده به‌صورت پروژه‌ای قابل دانلود تحویل داده می‌شود و شما می‌توانید آن را در جریان کاری دلخواه خود بررسی، ویرایش، تست، نسخه‌بندی و مستقر کنید. API Besaz کارهای تکراری ساخت اسکلت بک‌اند را کاهش می‌دهد؛ برنامه تولیدشده برای اجرا به فراخوانی API Besaz وابسته نیست. تصمیم‌های معماری، یکپارچه‌سازی‌ها، بازبینی امنیتی و نگهداری همچنان بر عهده شماست.
در صورت فعال‌سازی، پروژه تولیدشده می‌تواند لاگ ساخت‌یافته، شناسه درخواست، متریک‌های Prometheus و endpointهای سلامت و آمادگی داشته باشد؛ اجزای استقرار Grafana، Loki و ابزارهای مرتبط نیز بر اساس پیکربندی اضافه می‌شوند. برای سنجش کارایی واقعی، زمان پاسخ، خطاها و اشباع منابع را بررسی کنید و تنها به عدد درخواست در ثانیه تکیه نکنید.
پایگاه داده GeoLite2 در فایل ZIP پروژه‌های تولیدشده‌ای که GeoIP در آن‌ها فعال است، به‌طور پیش‌فرض قرار می‌گیرد. افزونه‌های Grafana داخل ZIP پروژه نیستند؛ بسته سازگار افزونه‌ها و نسخه به‌روز پایگاه داده GeoLite2 را از صفحه دانلودها دریافت کنید.
فایل افزونه‌های Grafana داخل ZIP پروژه تولیدشده قرار نمی‌گیرد. وقتی بسته ترکیبی سازگار در صفحه دانلودها فهرست شده است، آن را دریافت و فایل‌ها را به‌ترتیب در مسیرهای grafana/plugins/loki/ و grafana/plugins/prometheus/ استخراج کنید. اگر بسته ترکیبی در فهرست نبود، از پیوندهای رسمی زیر استفاده کنید. رفتن به صفحه دانلودها. راهنمای رسمی نصب افزونه‌های Grafana.
وقتی GeoIP فعال باشد، فایل پایگاه داده GeoLite2-Country.mmdb به‌طور پیش‌فرض در مسیر زیر داخل ZIP پروژه تولیدشده قرار می‌گیرد. برای به‌روزرسانی پروژه‌ای که قبلاً ساخته‌اید، نسخه تازه پایگاه داده را از صفحه دانلودها بگیرید و فایل قبلی را جایگزین کنید. در نبود پایگاه داده، نتیجه تشخیص کشور Unknown خواهد بود. مکان‌یابی مبتنی بر IP تقریبی است و نباید نشانی دقیق تلقی شود. رفتن به صفحه دانلودها.
app/geoip/GeoLite2-Country.mmdb دریافت GeoLite2 از MaxMind
هزینه تولید عدد ثابتی برای همه پروژه‌ها نیست. هزینه به تنظیمات هسته، ماژول‌های فعال و موجودیت‌ها بستگی دارد؛ برآورد سازنده هزینه دقیق پیکربندی را پیش از ثبت درخواست نشان می‌دهد.
بسته‌های فعلی را در صفحه تعرفه‌ها ببینید.
ابتدا پیام اعتبارسنجی یا وضعیت کار را بررسی کنید. هنگام درخواست کمک، گذرواژه، توکن، پیکربندی خصوصی یا فایل‌های محیطی را منتشر نکنید.
خلاصه اعتبارسنجی را باز کنید و ابتدا نخستین خطای گزارش‌شده را برطرف کنید، سپس دوباره اعتبارسنجی کنید. نام موجودیت و فیلد، نوع فیلد پشتیبانی‌شده، گزینه‌های enum، مقصد رابطه و مسیرهای endpoint را بررسی کنید. پیکربندی باید الزامات ساختاری موتور را داشته باشد تا تولید آغاز شود.
قابلیت اختیاری فقط زمانی تولید می‌شود که انتخاب و با بقیه Blueprint سازگار باشد. کلیدهای قابلیت و پیام‌های وابستگی را بررسی کنید. اگر گزینه استقرار فعال نشده باشد، فایل‌های مربوط به استقرار تولید نمی‌شوند.
پیش از ثبت درخواست دیگر، وضعیت پروژه را بررسی کنید تا کار تکراری ایجاد نشود. اگر وضعیت متوقف ماند یا چند بار شکست خورد، شناسه پروژه/کار و پیام خطای غیرحساس را ذخیره و با پشتیبانی تماس بگیرید. دسترس‌پذیری صف و worker می‌تواند بر زمان تکمیل اثر بگذارد.
پیوندهای دانلود زمان‌محدود هستند. به پروژه یا داشبورد برگردید و در صورت وجود، درخواست دانلود تازه کنید. اگر پروژه دیگر دیده نمی‌شود، شناسه آن را به پشتیبانی بدهید؛ نشانی امضاشده دانلود را عمومی منتشر نکنید.
ZIP را استخراج و ابتدا README آن را بخوانید. وابستگی‌های اعلام‌شده را نصب کنید، تنظیمات محیطی محلی را از روی نمونه بسازید و اسرار را در مخزن ثبت نکنید؛ سپس پایگاه داده و سرویس‌های فعال را تنظیم و مهاجرت‌ها را اجرا کنید. کد تولیدشده نقطه شروع است: پیش از انتشار، خطاهای تست، تنظیمات امنیتی، مجوزها و گزینه‌های استقرار عملیاتی را بررسی کنید.
فایل خروجی در اختیار شما قرار می‌گیرد و می‌توانید آن را بررسی و تغییر دهید. شرایط مجوز وابستگی‌ها و فایل‌های مجوز داخل پروژه تولیدشده را نیز رعایت کنید.
هر دو گزینه در پیکربندی پشتیبانی می‌شوند. انتخاب مناسب به بار کاری، هم‌زمانی، پشتیبان‌گیری و نیازهای عملیاتی برنامه شما بستگی دارد.
پیش از تولید، هزینه را در پنل بررسی کنید. اگر موجودی کافی نباشد، ابتدا باید توکن اضافه کنید؛ وضعیت پیکربندی ذخیره‌شده را از داشبورد بررسی کنید.
مدیریت افزونه‌ای است که به بسته احراز هویت نیاز دارد — کاربران باید وارد شوند تا به پنل مدیریت برسند.