پایه‌های FastAPI

چگونه پروژه‌های FastAPI خود را ساختاربندی کنیم؟

بخش اول: الگوی پایه (Blueprint)

در این مقاله، به بررسی دو رویکرد اصلی برای ساختاربندی پروژه‌های FastAPI می‌پردازیم و شرایطی که هرکدام مناسب‌تر هستند را توضیح می‌دهیم.

چرا ساختاربندی مناسب مهم است؟

دلایل اصلی و مهم برای ساختاربندی کد بر اساس بهترین شیوه‌ها عبارتند از:

1. افزایش قابلیت توسعه: کد ساختاربندی‌شده به‌ راحتی به همراه پروژه FastAPI شما رشد می‌کند.
2. سهولت نگهداری: کد واضح و قابل فهم باعث می‌شود به‌روزرسانی‌ها و رفع مشکلات ساده شوند.
3. همکاری منظم‌تر تیمی: ساختار واضح کمک می‌کند تیم‌ها به‌طور مؤثر با یکدیگر همکاری کنند.

تصویر تولیدشده توسط Dall-E با مفهوم: یک نقشه کلی انتزاعی نرم‌افزاری.

اصول کلیدی ساختاربندی پروژه‌ها

در توسعه برنامه‌های FastAPI، اهمیت زیادی دارد که اصول زیر را رعایت کنیم:

1. جدا سازی وظایف (Separation of Concerns): به تفکیک بخش‌های مختلف پروژه مثل مسیرها (routes)، مدل‌ها (models)، و منطق تجاری (business logic) بپردازیم تا وضوح و قابلیت نگهداری افزایش یابد.
2. ماژولار سازی (Modularization): برنامه FastAPI را به ماژول‌های قابل استفاده مجدد تقسیم کنیم تا کد مرتب و قابل مدیریت باشد.
3. تزریق وابستگی (Dependency Injection): اجزای برنامه را با تزریق وابستگی جدا کنیم که باعث انعطاف‌پذیری بیشتر و امکان تست ساده‌تر می‌شود. در FastAPI می‌توان از قابلیت‌های خود فریمورک مانند fastapi.Dependencies استفاده کرد.
4. قابلیت تست‌پذیری (Testability): نوشتن کد قابل تست در پروژه‌های FastAPI را اولویت قرار دهید. با استفاده از تزریق وابستگی و ایجاد ماک‌ها، می‌توان تست‌های قدرتمند و تضمین کیفیت داشت.

فرمت‌های ساختاربندی

برنامه‌های FastAPI را می‌توان به روش‌های مختلفی ساختاربندی کرد تا نیازهای متفاوت پروژه را پاسخ دهد.

دو رویکرد اصلی وجود دارد: یکی بر اساس نوع فایل و دیگری بر اساس عملکرد ماژول.

1. ساختاربندی بر اساس نوع فایل (File-Type)

در این روش، فایل‌ها بر اساس نوع دسته‌بندی می‌شوند (مثلاً API، عملیات CRUD، مدل‌ها، اسکیماها، روت‌ها) که توسط خود FastAPI پیشنهاد شده است.

این ساختار بیشتر برای میکروسرویس‌ها یا پروژه‌هایی با محدوده‌های محدود مناسب است:

1.  
2├── app  # شامل فایل‌های اصلی برنامه  
3│   ├── __init__.py   # این فایل باعث می‌شود "app" به یک پکیج پایتون تبدیل شود  
4│   ├── main.py       # فایل آغازین FastAPI  
5│   ├── dependencies.py # تعریف وابستگی‌هایی که روت‌ها استفاده می‌کنند  
6│   ├── routers  
7│   │   ├── __init__.py  
8│   │   ├── items.py  # مسیرها و اندپوینت‌های مرتبط با آیتم‌ها  
9│   │   └── users.py  # مسیرها و اندپوینت‌های مرتبط با کاربران  
10│   ├── crud  
11│   │   ├── __init__.py  
12│   │   ├── item.py  # عملیات CRUD برای آیتم‌ها  
13│   │   └── user.py  # عملیات CRUD برای کاربران  
14│   ├── schemas  
15│   │   ├── __init__.py  
16│   │   ├── item.py  # اسکیماهای Pydantic برای آیتم‌ها  
17│   │   └── user.py  # اسکیماهای Pydantic برای کاربران  
18│   ├── models  
19│   │   ├── __init__.py  
20│   │   ├── item.py  # مدل‌های پایگاه داده برای آیتم‌ها  
21│   │   └── user.py  # مدل‌های پایگاه داده برای کاربران  
22│   ├── external_services  
23│   │   ├── __init__.py  
24│   │   ├── email.py          # توابع مربوط به ارسال ایمیل  
25│   │   └── notification.py   # توابع مربوط به ارسال اعلان‌ها  
26│   └── utils  
27│       ├── __init__.py  
28│       ├── authentication.py  # توابع احراز هویت  
29│       └── validation.py      # توابع اعتبارسنجی  
30├── tests  
31│   ├── __init__.py  
32│   ├── test_main.py  
33│   ├── test_items.py  # تست‌های ماژول آیتم‌ها  
34│   └── test_users.py  # تست‌های ماژول کاربران  
35├── requirements.txt  
36├── .gitignore  
37└── README.md

اجزاء این ساختار

• app/: شامل فایل‌های اصلی برنامه
• main.py: شروع‌کننده برنامه FastAPI
• dependencies.py: تعریف وابستگی‌هایی که روت‌ها استفاده می‌کنند
• routers/: ماژول‌های روت‌ها
• crud/: ماژول‌های عملیات ایجاد، خواندن، بروزرسانی، حذف
• schemas/: مدل‌های پایدانتیک (Pydantic)
• models/: مدل‌های پایگاه داده
• external_services/: ماژول‌هایی جهت تعامل با سرویس‌های خارجی
• utils/: ماژول‌هایی شامل کدهای کمکی
• tests/: ماژول‌های تست

---

2. ساختاربندی بر اساس عملکرد ماژول (Module-Functionality)

در روش دوم، فایل‌ها را بر اساس عملکرد پکیج سازماندهی می‌کنیم؛ مثلاً پکیج احراز هویت (auth)، پکیج کاربران (users)، یا پکیج پست‌ها (posts).

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

این روش توسط مخزن fastapi-best-practices توصیه شده است.

ساختار نمونه:

1fastapi-project  
2├── alembic/  
3├── src  
4│   ├── auth  
5│   │   ├── router.py         # روت اصلی پکیج احراز هویت با همه اندپوینت‌ها  
6│   │   ├── schemas.py        # مدل‌های پایدانتیک  
7│   │   ├── models.py         # مدل‌های پایگاه داده  
8│   │   ├── dependencies.py   # وابستگی‌های روت  
9│   │   ├── config.py         # پیکربندی‌های محلی  
10│   │   ├── constants.py      # ثابت‌ها و موارد مربوط به این ماژول  
11│   │   ├── exceptions.py     # خطاهای مختص این ماژول  
12│   │   ├── service.py        # منطق کسب و کار مربوط به این ماژول  
13│   │   └── utils.py          # توابع کمکی غیر تجاری (non-business logic)  
14│   ├── aws  
15│   │   ├── client.py  # مدل ارتباط با سرویس بیرونی  
16│   │   ├── schemas.py  
17│   │   ├── config.py  
18│   │   ├── constants.py  
19│   │   ├── exceptions.py  
20│   │   └── utils.py  
21│   └── posts  
22│       ├── router.py  
23│       ├── schemas.py  
24│       ├── models.py  
25│       ├── dependencies.py  
26│       ├── constants.py  
27│       ├── exceptions.py  
28│       ├── service.py  
29│       └── utils.py  
30│   ├── config.py      # پیکربندی‌های سراسری  
31│   ├── models.py      # مدل‌های پایگاه داده سراسری  
32│   ├── exceptions.py  # خطاهای سراسری  
33│   ├── pagination.py  # ماژول سراسری مثلاً صفحه‌بندی  
34│   ├── database.py    # موارد مربوط به اتصال به دیتابیس  
35│   └── main.py  
36├── tests/  
37│   ├── auth  
38│   ├── aws  
39│   └── posts  
40├── templates/  
41│   └── index.html  
42├── requirements  
43│   ├── base.txt  
44│   ├── dev.txt  
45│   └── prod.txt  
46├── .env  
47├── .gitignore  
48├── logging.ini  
49└── alembic.ini

اجزاء این ساختار

تمام دایرکتوری‌های حوزه (domain) را داخل پوشه src قرار دهید.

• src/ بالاترین سطح برنامه که شامل مدل‌ها، پیکربندی‌ها، ثابت‌ها و… است.
• src/main.py نقطه شروع برنامه و راه‌اندازی FastAPI.

برای هر پکیج:

• router.py: هسته پکیج با همه اندپوینت‌ها
• schemas.py: مدل‌های پایدانتیک
• models.py: مدل‌های دیتابیس
• service.py: منطق تجاری اختصاصی ماژول
• dependencies.py: وابستگی‌های روت
• constants.py: ثابت‌ها و کدهای خطای اختصاصی ماژول
• config.py: متغیرهای محیطی و تنظیمات
• utils.py: توابع کمکی غیر تجاری مثل نرمال‌سازی پاسخ یا غنی‌سازی داده
• exceptions.py: استثناهای اختصاصی مثلا PostNotFound, InvalidUserData

---

وقتی یک پکیج نیاز به سرویس‌ها یا وابستگی‌ها یا ثابت‌هایی از پکیج‌های دیگر داشت، بهتر است آن‌ها را با نام ماژولی مشخص وارد (import) کنید تا ابهام ایجاد نشود:

1from src.auth import constants as auth_constants  
2from src.notifications import service as notification_service  
3from src.posts.constants import ErrorCode as PostsErrorCode  # در صورت وجود ErrorCode استاندارد در ماژول constants هر پکیج

در نهایت

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

ما دو ساختار اصلی را بررسی کردیم: ساختار مبتنی بر نوع فایل و ساختار مبتنی بر عملکرد ماژول.

ساختار نوع فایل (File-Type) که توسط خود فریمورک FastAPI معرفی شده، فایل‌ها را بر اساس نوعشان مثل روت‌ها، اسکیماها، مدل‌ها جدا می‌کند و برای معماری‌های میکروسرویس که مسئولیت‌های مشخص دارند، مناسب است.

ساختار عملکرد ماژول (Module-Functionality) فایل‌ها را بر اساس عملکرد بسته‌بندی می‌کند، برای پروژه‌های بزرگ یکپارچه مناسب‌تر است و سازماندهی و نگهداری بهتری فراهم می‌کند.

انتخاب ساختار مناسب بستگی به ابعاد پروژه، پیچیدگی و طراحی معماری شما دارد. در نهایت، هر ساختاری که انتخاب کنید، تمرکز بر نظم و وضوح کد باعث موفقیت بلندمدت پروژه‌های FastAPI شما خواهد شد.

---

منابع

• برنامه‌های بزرگتر و چندفایلی - FastAPI
• پروژه fastapi-best-practices در گیت‌هاب