طراحی API پایتون با FastAPI؛ و اینکه چرا Sonobe را ساختم

پایتون زبانی است که وقتی مسئله واقعاً مسئلهٔ منطق است سراغش می‌روم: API، اتوماسیون، کارهای داده‌محور و خودِ فریم‌ورک‌سازی. از فناوری‌های هستهٔ حرفه‌ای من است، با آن برنامه‌نویسی درس می‌دهم و پایهٔ Sonobe است، فریم‌ورک بک‌اندی که ساخته‌ام. برتری پایتون در این مقطع مد روز نیست؛ ترکیب یک اکوسیستم بزرگ و بالغ است با کدی که یک سال بعد هم — وقتی خودم برمی‌گردم سراغش — هنوز خوانا مانده است.

اما داخل خود پایتون، «کدام فریم‌ورک؟» یک تصمیم معماری واقعی است و من حرفه‌ای با دو پاسخ کار می‌کنم: FastAPI و جنگو. این دو جای هم را نمی‌گیرند و وانمود کردن به برعکسش همان راهی است که تیم‌ها را به بازسازی پنل ادمین داخل یک میکروفریم‌ورک یا کلنجار با ORM در یک سرویس حساس به تأخیر می‌رساند.

شرط‌بندی اصلی FastAPI این است: تایپ، مستنداتی است که نمی‌تواند از واقعیت عقب بیفتد. مدل درخواست و پاسخ را یک‌بار تعریف می‌کنی و اعتبارسنجی، سریال‌سازی و مستندات OpenAPI همه از همان منبع واحد می‌آیند. در نوشتهٔ لاراول گفتم API یک قرارداد است؛ FastAPI فریم‌ورکی است که این قرارداد را به معنای واقعی کلمه در سیستم تایپ حک می‌کند. برای سرویس‌های API-محور — مخصوصاً وقتی مصرف‌کننده سرویس‌های دیگرند، فرانت‌اندی که دست تو نیست، یا این روزها ایجنت‌ها — این صراحت ارزش زیادی دارد.

قصهٔ async هم مهم است، ولی صادقانه در ترتیب اهمیت دنیای واقعی دوم است. بیشتر APIها شکل ورودی/خروجی دارند و FastAPI خوب از پسشان برمی‌آید، اما پروژه‌هایی که دیده‌ام با آن موفق شده‌اند به خاطر روشن بودن قراردادها و قابل پیمایش ماندن کد موفق شده‌اند، نه بزرگ‌تر بودن یک عدد بنچمارک. سرعت باعث می‌شود فریم‌ورکی انتخاب شود؛ وضوح است که در سال سوم زنده نگهش می‌دارد.

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

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

بعد از چند پروژهٔ FastAPI، یک اصطکاک مدام تکرار می‌شد: قابلیت تازه باید اضافه می‌شد بی‌آنکه دست به قلب برنامه بخورد و ماژول‌ها مرز روشن‌تری از «یک پوشهٔ در حال رشدِ روترها» می‌خواستند. این‌طور شد که Sonobe را روی FastAPI ساختم: هسته‌ای ماژولار و مستقل که قابلیت‌های اختصاصی در آن به شکل افزونه‌های آمادهٔ نصب اضافه می‌شوند، نه دستکاری کد مشترک. همان غریزه‌ای است که بعداً با Yoshi به فرانت‌اند بردم: اول مرز، بعد راحتی؛ چون وقتی راحتی کهنه شد، مرز است که می‌ماند.

فریم‌ورک ساختن روی فریم‌ورک تا وقتی قیمت گزینهٔ دیگر را حساب نکرده‌ای تجملی به نظر می‌رسد. هر کدبیس جدی بالاخره یک فریم‌ورک داخلی می‌سازد — قراردادها، هلپرها، الگوهای ماژول — فقط معمولاً اتفاقی و بی‌مستندات، بین فیچرها. Sonobe همان لایه است، ولی عمدی: نام‌دار، ساخت‌یافته و قابل استفاده در پروژه‌های مختلف به جای اختراع دوباره در هر کدام. فریم‌ورک ساخته شده؛ کدش هنوز عمومی نیست و قرار است متن‌بازش کنم.

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

قراردادهای تایپ‌دار FastAPI پایهٔ خیلی خوبی برای این کار از آب درآمده‌اند، چون حقیقتِ ماشین‌خوان از قبل در مدل‌ها هست. ابزارسازی من برای توسعه‌دهندگان از چند طرف دور همین ایده می‌چرخد: سیستم‌هایی خوب پیر می‌شوند که بشود ساختارشان را توضیح داد؛ به یک هم‌تیمی، به نگه‌دار آینده یا به ایجنتی که قرار است دستشان بزند. PromptForge از سمت بریف به آن نزدیک می‌شود و Sonobe از سمت خود فریم‌ورک.

اگر امروز در حال انتخابی، من با این ترتیب جلو می‌روم: اول، محصول API است یا اپلیکیشن؟ دوم، مصرف‌کننده کیست؛ فرانت‌اند خودت، طرف سوم یا ایجنت‌ها؟ سوم، چقدر از باتری جنگو را در غیر این صورت باید با دست بسازی؟ به این‌ها صادقانه جواب بدهی فریم‌ورک تقریباً خودش انتخاب می‌شود. کاری که نمی‌کنم انتخاب از روی اسکرین‌شات بنچمارک است؛ هیچ‌کدام از دردهای پروداکشن من از سقف درخواست‌برثانیهٔ یک فریم‌ورک نیامده است.

نقشهٔ کار خودم حالا ثابت است: FastAPI برای سرویس‌های قراردادمحور و به‌عنوان پایهٔ Sonobe، جنگو وقتی اپلیکیشن باتری‌هایش را می‌خواهد، لاراول وقتی پروژه شکل PHP دارد و Rust وقتی سیستم آن درجه از کنترل را لازم دارد. فریم‌ورک ابزار است؛ هنر این است که بدانی مسئله‌ات واقعاً چیست. مسیر عملی‌ای هم که برای وارد کردن FastAPI به یک تیم پیشنهاد می‌کنم تدریجی است: از یک سرویس کوچک و محصور شروع کن — یک مبدل سند، یک اندپوینت گزارش یا یک اینتگریشن محدود — آن را پشت همان احراز هویت سیستم اصلی بگذار و بگذار تیم با داستان دیپلوی، لاگ و رول‌بکش راحت شود؛ بعد به آن مسئولیت بیشتری بده. انتخاب فریم‌ورک در نهایت انتخاب نوع نگهداری است: سؤال فقط این نیست که نسخهٔ اول چقدر سریع می‌آید، مهم این است که تغییر دهم چقدر آرام می‌نشیند؛ و FastAPI تا اینجای کار مدام همان تغییر دهمِ آرام را به من داده است. اگر مسئلهٔ تو یک API پایتونی است که باید درست ساخته شود، از رزومه‌ام شروع کن و حرف بزنیم.