آموزش FastAPI: ساخت APIهای سریع و مدرن با پایتون

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

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

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

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

FastAPI چیست؟

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

در قلب FastAPI دو مفهوم مهم قرار دارد: استفاده از type hintهای پایتون و پشتیبانی کامل از پردازش غیرهمزمان (async). همین دو ویژگی باعث می‌شوند هم کدنویسی خواناتر شود و هم عملکرد API در سطح بالایی قرار بگیرد.

FastAPI بر پایه‌ی ابزارهایی مثل Starlette (برای مدیریت وب) و Pydantic (برای اعتبارسنجی داده‌ها) ساخته شده است. این ترکیب باعث می‌شود بتوانید بدون نوشتن کدهای تکراری برای اعتبارسنجی یا مدیریت درخواست‌ها، APIهایی دقیق و قابل اعتماد بسازید.

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

چرا FastAPI سریع است؟

یکی از اولین سوال‌هایی که درباره FastAPI مطرح می‌شود این است که این «سرعت» دقیقا از کجا می‌آید و چه چیزی آن را از فریمورک‌های سنتی متمایز می‌کند.

پاسخ را باید در ترکیب چند تصمیم معماری جست‌وجو کرد. مهم‌ترین آن‌ها پشتیبانی کامل از async/await در پایتون است. FastAPI بر پایه ASGI طراحی شده، یعنی برخلاف مدل‌های قدیمی‌تر که درخواست‌ها را به‌صورت همزمان و بلاک‌شونده پردازش می‌کردند، می‌تواند تعداد زیادی درخواست را به شکل غیرهمزمان مدیریت کند. این موضوع در سرویس‌هایی با ترافیک بالا تفاوت قابل توجهی ایجاد می‌کند.

عامل مهم دیگر، استفاده از کتابخانه‌های بهینه و تخصصی است. FastAPI برای مدیریت لایه وب از Starlette و برای اعتبارسنجی و تبدیل داده‌ها از Pydantic استفاده می‌کند. این ترکیب باعث می‌شود بخش‌های سنگین مثل parsing داده‌ها یا validation با کمترین overhead انجام شوند.

نکته مهم‌تر این است که بخش زیادی از کارهایی که در فریمورک‌های دیگر باید به‌صورت دستی نوشته شود، در FastAPI به‌صورت خودکار انجام می‌شود. همین کاهش کد تکراری (boilerplate) نه‌تنها سرعت توسعه را بالا می‌برد، بلکه احتمال خطا را هم کاهش می‌دهد.

در مجموع، سرعت FastAPI فقط به اجرای سریع‌تر کد محدود نمی‌شود؛ بلکه نتیجه یک طراحی است که هم در سطح اجرا بهینه است و هم در سطح توسعه، فرآیند ساخت API را ساده‌تر و مستقیم‌تر می‌کند.

راه‌اندازی اولین پروژه FastAPI

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

در ابتدا فقط کافی است FastAPI و یک سرور ASGI مثل Uvicorn نصب شود. سپس می‌توان یک فایل ساده پایتون ساخت و اولین endpoint را تعریف کرد. در FastAPI هر endpoint با استفاده از decoratorها تعریف می‌شود و همین موضوع باعث می‌شود ساختار کد بسیار شفاف و قابل‌خواندن باشد.

بعد از تعریف endpoint، سرور با Uvicorn اجرا می‌شود. برخلاف فریمورک‌های قدیمی‌تر، نیازی به تنظیمات پیچیده یا ساختارهای سنگین نیست، تنها با یک دستور ساده، API در حال اجرا خواهد بود. در همین مرحله اولیه می‌توان اولین تفاوت‌ها را دید: FastAPI به‌صورت پیش‌فرض از type hintها برای تشخیص نوع داده‌ها استفاده می‌کند، ورودی‌ها را اعتبارسنجی می‌کند و حتی مستندات اولیه API را به‌صورت خودکار تولید می‌کند. این یعنی بدون نوشتن حتی یک خط کد اضافه، یک API قابل استفاده در اختیار دارید.

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

اول باید FastAPI و یک سرور ASGI مثل Uvicorn را نصب کنید:

pip install fastapi uvicorn

حالا یک فایل مثلاً به نام main.py بسازید و کد زیر را داخل آن قرار دهید:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello FastAPI"}

در این مرحله شما فقط یک endpoint ساده دارید که وقتی آدرس / را باز کنید، یک پیام JSON برمی‌گرداند.

برای اجرای پروژه از دستور زیر استفاده کنید:

uvicorn main:app --reload

بعد از اجرا، سرور روی آدرس زیر بالا می‌آید:

http://127.0.0.1:8000

اگر وارد این آدرس شوید، خروجی زیر را می‌بینید:

{"message": "Hello FastAPI"}

یکی از ویژگی‌های مهم این مرحله، وجود حالت --reload است. این گزینه باعث می‌شود هر تغییری در کد بدهید، سرور به‌صورت خودکار ری‌استارت شود و نیاز به اجرای دوباره نداشته باشید.

در همین حال اگر آدرس زیر را باز کنید:

http://127.0.0.1:8000/docs

یک مستندات آماده و تعاملی (Swagger UI) می‌بینید که FastAPI به‌صورت خودکار برای شما ساخته است. این بخش یکی از نقاط قوت اصلی FastAPI است، چون بدون نوشتن حتی یک خط کد اضافه، یک API قابل تست و مستندسازی شده دارید.

ساخت یک API واقعی (CRUD ساده)

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

در این مثال یک سیستم ساده «Todo» می‌سازیم که بتوانیم کارها را اضافه کنیم، لیست بگیریم و حذف کنیم.

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

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# مدل داده
class Todo(BaseModel):
    id: int
    title: str
    completed: bool = False

# دیتای موقت (در حافظه)
todos = []

افزودن یک Todo

@app.post("/todos")
def create_todo(todo: Todo):
    todos.append(todo)
    return todo

دریافت همه Todoها

@app.get("/todos")
def get_todos():
    return todos

دریافت یک Todo مشخص

@app.get("/todos/{todo_id}")
def get_todo(todo_id: int):
    for todo in todos:
        if todo.id == todo_id:
            return todo
    return {"error": "Todo not found"}

حذف یک Todo

@app.delete("/todos/{todo_id}")
def delete_todo(todo_id: int):
    global todos
    todos = [todo for todo in todos if todo.id != todo_id]
    return {"message": "Deleted"}

در این مثال چند نکته مهم را می‌شود دید:

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

همچنین استفاده از routeهای ساده مثل GET ،POST ،DELETE باعث می‌شود طراحی API کاملا شفاف و استاندارد باشد.

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

مدیریت دیتابیس در FastAPI

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

در FastAPI معمولا از SQLAlchemy برای ارتباط با دیتابیس استفاده می‌شود، چون هم پایدار است و هم انعطاف‌پذیری بالایی دارد.

در ساده‌ترین حالت، ابتدا باید اتصال به دیتابیس را تعریف کنید (مثلا SQLite برای شروع):

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "sqlite:///./test.db"

engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

سپس یک الگوی مهم در FastAPI وارد می‌شود: Dependency Injection. این مکانیزم کمک می‌کند هر درخواست یک session مستقل به دیتابیس داشته باشد.

from fastapi import Depends

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

حالا می‌توانیم این اتصال را در endpointها استفاده کنیم:

@app.get("/items")
def get_items(db = Depends(get_db)):
    return db.query(Item).all()

در کنار این ساختار، معمولا یک مدل ORM هم تعریف می‌شود که جدول دیتابیس را مشخص می‌کند. FastAPI خودش مستقیما دیتابیس را مدیریت نمی‌کند، اما با ترکیب SQLAlchemy و Pydantic یک جریان کامل برای دریافت، اعتبارسنجی و ذخیره داده‌ها ایجاد می‌شود.

احراز هویت (Authentication) در FastAPI

وقتی API وارد مرحله واقعی استفاده در یک محصول می‌شود، یکی از مهم‌ترین نیازها کنترل دسترسی است. یعنی باید مشخص شود چه کسی اجازه دارد چه کاری انجام دهد. در FastAPI این مسئله معمولا با استفاده از JWT (JSON Web Token) حل می‌شود.

ایده کلی ساده است: کاربر یک‌بار لاگین می‌کند و در پاسخ یک توکن دریافت می‌کند. از آن به بعد، این توکن همراه هر درخواست ارسال می‌شود و سرور بر اساس آن تصمیم می‌گیرد درخواست معتبر است یا نه.

ابتدا یک endpoint ساده برای لاگین تعریف می‌شود:

from fastapi import FastAPI
from datetime import datetime, timedelta
import jwt

app = FastAPI()

SECRET_KEY = "mysecretkey"
ALGORITHM = "HS256"

@app.post("/login")
def login(username: str):
    expire = datetime.utcnow() + timedelta(hours=1)
    token = jwt.encode(
        {"sub": username, "exp": expire},
        SECRET_KEY,
        algorithm=ALGORITHM
    )
    return {"access_token": token}

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

from fastapi import Depends, HTTPException
from fastapi.security import HTTPBearer
import jwt

security = HTTPBearer()

def get_current_user(token=Depends(security)):
    try:
        payload = jwt.decode(token.credentials, SECRET_KEY, algorithms=[ALGORITHM])
        return payload["sub"]
    except:
        raise HTTPException(status_code=401, detail="Invalid token")

و در نهایت می‌توانیم یک مسیر محافظت‌شده بسازیم:

@app.get("/profile")
def profile(user=Depends(get_current_user)):
    return {"user": user}

در این ساختار، FastAPI نقش مهمی در ساده کردن جریان امنیتی دارد. به‌جای پیاده‌سازی دستی مدیریت session یا cookie، همه‌چیز با یک الگوی مشخص و قابل‌گسترش انجام می‌شود. در پروژه‌های واقعی معمولا این بخش با OAuth2 و سطح‌بندی دسترسی (roles) تکمیل می‌شود، اما همین ساختار پایه، ستون اصلی امنیت در APIهای مدرن محسوب می‌شود.

مفاهیم اصلی در FastAPI

• Path Parameters: پارامترهایی که مستقیما از مسیر URL استخراج می‌شوند و معمولا برای شناسایی یک منبع خاص استفاده می‌شوند (مثل گرفتن اطلاعات یک کاربر با ID).

• Query Parameters: پارامترهایی که در انتهای URL و بعد از ? ارسال می‌شوند و بیشتر برای فیلتر کردن، جستجو یا تنظیم رفتار درخواست کاربرد دارند.

• Request Body: داده‌هایی که داخل بدنه درخواست (معمولا در POST/PUT) ارسال می‌شوند و برای ساخت یا بروزرسانی اطلاعات استفاده می‌شوند.

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

• Response Model: مشخص می‌کند API دقیقا چه ساختاری را به عنوان خروجی برگرداند و باعث استاندارد شدن پاسخ‌ها می‌شود.

• Dependency Injection: مکانیزمی برای تزریق وابستگی‌ها (مثل دیتابیس یا کاربر احراز هویت‌شده) به داخل endpointها بدون نوشتن کد تکراری.

• Status Codes: کنترل وضعیت پاسخ‌ها (مثل 200، 201، 404) برای مشخص کردن نتیجه دقیق هر درخواست.

• Middleware: لایه‌ای بین درخواست و پاسخ که برای پردازش‌های مشترک مثل لاگ‌گیری، احراز هویت یا مدیریت CORS استفاده می‌شود.

مستندسازی خودکار API

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

به محض اینکه یک پروژه FastAPI اجرا می‌شود، دو رابط مستندات به‌صورت پیش‌فرض در اختیار شما قرار می‌گیرد:

• Swagger UI در مسیر /docs

• ReDoc در مسیر /redoc

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

ReDoc در مقابل، یک نمای تمیزتر و مناسب‌تر برای ارائه مستندات به تیم‌ها یا کلاینت‌ها فراهم می‌کند. تمرکز آن بیشتر روی خوانایی و ساختار مستندات است تا تعامل مستقیم.

نکته مهم اینجاست که FastAPI این مستندات را بر اساس همان type hintها و مدل‌هایی که در کد تعریف کرده‌اید تولید می‌کند. یعنی هر تغییری در ساختار API به‌صورت خودکار در مستندات هم منعکس می‌شود، بدون نیاز به هماهنگی دستی. در نتیجه، مستندسازی در FastAPI نه یک مرحله جداگانه، بلکه بخشی از خود طراحی API است؛ چیزی که باعث می‌شود هم توسعه سریع‌تر شود و هم خطای انسانی در مستندات به حداقل برسد.

جمع‌بندی

FastAPI یک فریمورک مدرن برای ساخت API در پایتون است که با تکیه بر سرعت، سادگی و قابلیت‌های async، فرآیند توسعه بک‌اند را بسیار روان‌تر می‌کند.

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

در نهایت، FastAPI بیشتر از یک فریمورک، یک استاندارد جدید برای طراحی APIهای سریع و قابل توسعه است.