اگر می‌خواهید یک API سریع، خوانا و قابل توسعه برای اپلیکیشن وب یا موبایل بسازید، FastAPI یکی از بهترین انتخاب‌های پایتون است. این فریم‌ورک با type hintهای پایتون، اعتبارسنجی خودکار داده‌ها و مستندسازی تعاملی، بخش زیادی از کارهای تکراری را از دوش شما برمی‌دارد. در این آموزش یک سرویس کوچک اما استاندارد می‌سازیم و از ساخت اولین مسیر تا مدیریت خطا، مدل داده و اجرای پروژه را قدم‌به‌قدم جلو می‌بریم.

چرا FastAPI برای ساخت API انتخاب مناسبی است؟

FastAPI یک فریم‌ورک مدرن پایتون بر پایه Starlette و Pydantic است که از کد ناهمگام، اعتبارسنجی نوع‌ها و استاندارد OpenAPI پشتیبانی می‌کند. نتیجه، APIای سریع با مستندات آماده در آدرس‌های /docs و /redoc است. اگر ساختار پروژه و قرارداد ورودی و خروجی را از ابتدا درست تعریف کنید، همین ابزار کوچک می‌تواند پایه یک سرویس واقعی باشد؛ در ادامه می‌بینید چطور.

ساخت محیط پروژه FastAPI

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

mkdir task-api
cd task-api
python -m venv .venv
.venv\Scripts\activate
pip install fastapi uvicorn

در لینوکس یا macOS مسیر فعال‌سازی به شکل source .venv/bin/activate است. سپس فایل main.py را بسازید. برای یک پروژه تیمی بهتر است وابستگی‌ها را در فایل requirements.txt ثبت کنید:

fastapi
uvicorn[standard]

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

task-api/
├── .venv/
├── main.py
└── requirements.txt

ساخت اولین مسیر در FastAPI

در ساده‌ترین حالت، یک شیء از FastAPI می‌سازیم و با decorator مسیر GET را تعریف می‌کنیم:

from fastapi import FastAPI

app = FastAPI(title="Task API", version="1.0.0")

@app.get("/")
def home():
    return {"message": "Task API is running"}

@app.get("/tasks/{task_id}")
def get_task(task_id: int):
    return {"id": task_id, "title": "یادگیری FastAPI", "done": False}

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

اجرای سرور و تست مستندات تعاملی

سرور توسعه را با دستور زیر اجرا کنید:

uvicorn main:app --reload

گزینه --reload در زمان توسعه مفید است و پس از تغییر فایل، سرور را دوباره بارگذاری می‌کند. حالا آدرس http://127.0.0.1:8000/docs را باز کنید. در صفحه Swagger می‌توانید مسیرها را ببینید، پارامتر وارد کنید و پاسخ واقعی API را بدون نصب ابزار جداگانه بررسی کنید. آدرس /openapi.json نیز قرارداد ماشین‌خوان API را نمایش می‌دهد.

تعریف مدل درخواست و پاسخ با Pydantic

بازگرداندن دیکشنری برای نمونه اولیه کافی است، اما API واقعی باید بداند چه داده‌ای می‌پذیرد و چه داده‌ای تحویل می‌دهد. برای این کار از مدل‌های Pydantic استفاده کنید:

from pydantic import BaseModel, Field

class TaskCreate(BaseModel):
    title: str = Field(min_length=3, max_length=100)
    description: str | None = None

class Task(BaseModel):
    id: int
    title: str
    description: str | None = None
    done: bool = False

اکنون مدل را در مسیر POST به کار ببرید. FastAPI بدنه JSON را می‌خواند، آن را اعتبارسنجی می‌کند و نمونه‌ای از TaskCreate در اختیار تابع می‌گذارد:

tasks: list[Task] = []

@app.post("/tasks", response_model=Task, status_code=201)
def create_task(payload: TaskCreate):
    task = Task(id=len(tasks) + 1, **payload.model_dump())
    tasks.append(task)
    return task

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

پارامترهای مسیر، query و بدنه چه تفاوتی دارند؟

پارامتر داخل آدرس، مانند /tasks/3، معمولاً شناسه منبع است. query parameter برای فیلتر، جست‌وجو یا صفحه‌بندی به کار می‌رود و بدنه درخواست داده اصلی را حمل می‌کند:

from fastapi import Query

@app.get("/tasks", response_model=list[Task])
def list_tasks(done: bool | None = Query(default=None), limit: int = Query(default=20, le=100)):
    result = tasks
    if done is not None:
        result = [task for task in result if task.done == done]
    return result[:limit]

با این الگو، درخواست /tasks?done=false&limit=10 فقط کارهای انجام‌نشده را برمی‌گرداند. محدود کردن limit از پاسخ‌های بسیار بزرگ و فشار غیرضروری روی سرویس جلوگیری می‌کند.

مدیریت خطا و پاسخ‌های قابل پیش‌بینی

کاربر باید برای منبع پیدا نشده پاسخ 404 بگیرد، نه یک خطای مبهم یا فهرست خالی. HTTPException راه ساده و استاندارد این کار است:

from fastapi import HTTPException

@app.get("/tasks/{task_id}", response_model=Task)
def get_task(task_id: int):
    for task in tasks:
        if task.id == task_id:
            return task
    raise HTTPException(status_code=404, detail="Task not found")

پیام خطا را برای کاربر روشن و برای کلاینت پایدار نگه دارید. در پروژه‌های بزرگ‌تر می‌توانید یک قالب مشترک برای خطاها تعریف کنید تا همه مسیرها ساختار یکسانی داشته باشند. اطلاعات حساس مانند stack trace، مسیر فایل و توکن‌ها نباید در پاسخ عمومی قرار بگیرند.

ساختار پیشنهادی برای پروژه‌های واقعی

وقتی تعداد مسیرها بیشتر شد، همه‌چیز را در main.py نگه ندارید. تقسیم مسئولیت، تست‌نویسی و تغییر پایگاه داده را ساده‌تر می‌کند:

app/
├── main.py
├── routers/
│   └── tasks.py
├── schemas/
│   └── tasks.py
├── services/
│   └── task_service.py
└── tests/
    └── test_tasks.py

در این ساختار، router فقط HTTP و status code را مدیریت می‌کند، schema قرارداد داده است و service منطق کسب‌وکار را نگه می‌دارد. برای اتصال به دیتابیس نیز یک لایه repository یا dependency جدا بسازید. این کار باعث می‌شود تست سرویس بدون اجرای وب‌سرور ممکن باشد.

استفاده از dependency برای کدهای مشترک

احراز هویت، اتصال دیتابیس و بررسی دسترسی نباید در هر route تکرار شوند. FastAPI با Depends این وابستگی‌ها را تزریق می‌کند:

from fastapi import Depends

def current_user():
    return {"username": "demo"}

@app.get("/me")
def profile(user = Depends(current_user)):
    return user

در نسخه واقعی، تابع current_user توکن را بررسی می‌کند و کاربر را از دیتابیس می‌خواند. جدا بودن این منطق، جایگزین کردن روش احراز هویت یا نوشتن تست‌های مستقل را آسان می‌کند.

مقایسه FastAPI با Flask و Django REST Framework

هیچ فریم‌ورکی برای همه پروژه‌ها بهترین نیست. انتخاب را بر اساس اندازه تیم، نوع محصول و نیازهای معماری انجام دهید:

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

اگر هدف شما یک سرویس سبک، سرویس میکرو یا API با قرارداد دقیق است، FastAPI انتخابی منطقی است. اگر پنل مدیریت، ORM و قابلیت‌های کامل یک وب‌سایت یکپارچه را از ابتدا می‌خواهید، Django REST Framework ممکن است زمان بیشتری ذخیره کند.

تست، امنیت و آماده‌سازی برای انتشار

پیش از انتشار، مسیرهای اصلی را با pytest و TestClient تست کنید. حداقل سناریوهای ساخت موفق، ورودی نامعتبر و شناسه不存在 را پوشش دهید. همچنین این موارد را جدی بگیرید:

کلیدهای محرمانه را در فایل محیطی نگه دارید، نه در کد و مخزن عمومی.
برای ورودی‌ها محدودیت طول، نوع و حجم فایل تعیین کنید.
CORS را فقط برای دامنه‌های مورد نیاز باز کنید.
برای مسیرهای عمومی rate limit و ثبت لاگ بدون اطلاعات حساس در نظر بگیرید.
در محیط تولید از --reload استفاده نکنید و اجرای چند worker را متناسب با منابع سرور تنظیم کنید.

برای ایده گرفتن از ساخت ابزارهای پایتونی کاربردی، مقاله آموزش ساخت داشبورد خط فرمان تعاملی پایتون با Textual را هم بخوانید. اگر API شما قرار است به یک ربات متصل شود، راهنمای ساخت ربات تلگرام با پایتون مسیر مناسبی برای مرحله بعد است.

جمع‌بندی ساخت API با FastAPI

FastAPI با ترکیب type hint، مدل‌های Pydantic، مستندات OpenAPI و پشتیبانی از async، مسیر ساخت API پایتون را کوتاه و قابل اعتماد می‌کند. ابتدا یک پروژه کوچک بسازید، قرارداد ورودی و خروجی را مشخص کنید، خطاها را استاندارد نگه دارید و بعد منطق را به router، service و repository تقسیم کنید. چنین پایه‌ای هم برای نمونه اولیه سریع مناسب است و هم می‌تواند با رشد محصول توسعه پیدا کند.

سوالات متداول

آیا برای شروع FastAPI باید async را بلد باشیم؟

خیر. می‌توانید routeهای معمولی با def بنویسید و بعد برای عملیات ورودی/خروجی سنگین یا هم‌زمان، از async def استفاده کنید.

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

بله. راه‌اندازی آن سبک است و مستندات خودکار باعث می‌شود حتی یک API کوچک نیز قرارداد روشن و قابل تست داشته باشد.

آیا FastAPI خودش دیتابیس دارد؟

خیر. FastAPI لایه وب و API است. برای دیتابیس می‌توانید از SQLAlchemy، SQLModel یا کتابخانه‌های مناسب دیگر استفاده کنید و اتصال را با dependency مدیریت کنید.

آموزش ساخت API حرفه‌ای با FastAPI؛ از اولین مسیر تا مستندسازی خودکار