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

🚀 FastAPI در یک نگاه

• ⚡️ سرعت بالا: مبتنی بر Starlette و Pydantic، عملکردی هم‌تراز با Node.js و Go ارائه می‌دهد.
• ✅ اعتبارسنجی داده: با Pydantic به صورت خودکار داده‌ها را اعتبارسنجی و سریالایز می‌کند.
• 📝 مستندات خودکار: به صورت پیش‌فرض، مستندات API با Swagger UI و ReDoc تولید می‌کند.
• 🧩 تزریق وابستگی: سیستم قدرتمند Dependency Injection برای کاهش کدهای تکراری و افزایش ماژولاریتی.
• 🔄 کدنویسی Asynchronous: پشتیبانی کامل از `async/await` برای ساخت APIهای کارآمد.
• 🌟 تایپ‌هینتینگ پایتون: استفاده از قابلیت‌های تایپ‌هینتینگ پایتون برای بهبود کد و تشخیص خطا.

فهرست مطالب

• FastAPI چیست و چرا باید از آن استفاده کنیم؟
• پیش‌نیازها و نصب FastAPI
• ساخت اولین API با FastAPI
• پارامترهای مسیر (Path Parameters)
• پارامترهای کوئری (Query Parameters)
• درخواست بدنه (Request Body) با Pydantic
• اعتبارسنجی و مدیریت خطاها
• سیستم تزریق وابستگی (Dependency Injection)
• سازماندهی کد با APIRouter
• عملیات Asynchronous در FastAPI
• مقایسه FastAPI با سایر فریم‌ورک‌ها
• ادغام با پایگاه داده
• ملاحظات استقرار (Deployment)
• موارد استفاده واقعی FastAPI
• عیب‌یابی سریع (Troubleshooting)
• پرسش‌های متداول (FAQ)
• جمع‌بندی

FastAPI چیست و چرا باید از آن استفاده کنیم؟

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

مزایای کلیدی FastAPI

• سرعت باورنکردنی: عملکرد آن در حد فریم‌ورک‌های Golang و Node.js است. این سرعت به دلیل استفاده از Starlette برای وب و Uvicorn به عنوان سرور ASGI به دست می‌آید.
• کدنویسی سریع‌تر: به لطف تایپ‌هینتینگ و مستندات خودکار، کد کمتری می‌نویسید و در زمان صرفه‌جویی می‌کنید.
• خطای کمتر: اعتبارسنجی داده‌ها (Data Validation) با استفاده از Pydantic به صورت خودکار انجام می‌شود و بسیاری از خطاهای زمان اجرا را قبل از وقوع تشخیص می‌دهد.
• مستندات خودکار و تعاملی: Swagger UI و ReDoc به صورت خودکار و بدون نیاز به کد اضافی برای API شما تولید می‌شوند. این مستندات هم برای توسعه‌دهندگان و هم برای مصرف‌کنندگان API بسیار مفید هستند.
• کد کامل‌تر و خواناتر: تایپ‌هینتینگ به ابزارهای توسعه (IDE) کمک می‌کند تا تکمیل خودکار کد و بررسی خطا را به شکل بهتری انجام دهند.
• استانداردهای باز: FastAPI از استانداردهایی مثل OpenAPI و JSON Schema استفاده می‌کند.
• سیستم تزریق وابستگی قدرتمند: ساختار کد شما را ماژولار و قابل تست می‌کند.
• پشتیبانی کامل از Asynchronous: برای مدیریت درخواست‌های همزمان و ساخت APIهای مقیاس‌پذیر ایده‌آل است.

پیش‌نیازها و نصب FastAPI

برای شروع کار با FastAPI، تنها به کمی دانش پایتون (نسخه 3.7 به بالا) و ابزار مدیریت بسته `pip` نیاز دارید. اگر با پایتون آشنایی دارید، نصب FastAPI بسیار ساده است.

مراحل نصب

1. ایجاد محیط مجازی (Virtual Environment): همیشه توصیه می‌شود برای هر پروژه پایتون یک محیط مجازی جداگانه ایجاد کنید. این کار از تداخل بسته‌ها جلوگیری می‌کند.

python -m venv myenv
source myenv/bin/activate  # در لینوکس/مک
myenvScriptsactivate     # در ویندوز

2. نصب FastAPI و Uvicorn: FastAPI برای اجرا نیاز به یک سرور ASGI دارد و Uvicorn یکی از بهترین گزینه‌ها است.

pip install fastapi "uvicorn[standard]"

بخش [standard] در `uvicorn[standard]`، بسته‌های اضافی مانند `websockets` و `httptools` را نصب می‌کند که برای عملکرد بهتر توصیه می‌شود.

ساخت اولین API با FastAPI

حالا که FastAPI و Uvicorn را نصب کرده‌اید، بیایید اولین API خود را بسازیم. یک فایل به نام main.py ایجاد کنید و کد زیر را داخل آن قرار دهید:

# main.py
from fastapi import FastAPI

app = FastAPI()

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

در این کد:

• from fastapi import FastAPI: کلاس FastAPI را ایمپورت می‌کنیم.
• app = FastAPI(): یک نمونه از اپلیکیشن FastAPI ایجاد می‌کنیم.
• @app.get("/"): این یک “دکوراتور” است که به FastAPI می‌گوید تابع read_root باید درخواست‌های GET را برای مسیر / هندل کند.
• async def read_root():: یک تابع پایتون تعریف می‌کنیم. کلمه کلیدی async نشان می‌دهد که این تابع یک تابع asynchronous است.
• return {"message": "Hello FastAPI! 🎉"}: یک دیکشنری پایتون را برمی‌گرداند که FastAPI آن را به صورت JSON به کلاینت پاسخ می‌دهد.

اجرای API

برای اجرای این API، ترمینال را در همان دایرکتوری که فایل main.py را ساخته‌اید باز کنید و دستور زیر را اجرا کنید:

uvicorn main:app --reload

در این دستور:

• main: نام فایل پایتون شما (بدون پسوند .py).
• app: نام شیء FastAPI که در فایل main.py ایجاد کرده‌اید (app = FastAPI()).
• --reload: این فلگ باعث می‌شود سرور به طور خودکار پس از هر تغییری در کدهای شما، ری‌استارت شود. این قابلیت برای توسعه بسیار مفید است.

بعد از اجرای دستور، پیامی شبیه به این را خواهید دید:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [11308]
INFO:     Started server process [11310]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

حالا می‌توانید مرورگر خود را باز کرده و به آدرس http://127.0.0.1:8000 بروید. پاسخ {"message": "Hello FastAPI! 🎉"} را مشاهده خواهید کرد.

مستندات خودکار (Automatic Docs)

یکی از بهترین قابلیتهای FastAPI، تولید خودکار مستندات API است. این مستندات بر اساس استاندارد OpenAPI (که قبلاً Swagger نامیده می‌شد) تولید می‌شوند و به دو شکل در دسترس هستند:

• Swagger UI: به آدرس http://127.0.0.1:8000/docs بروید. یک رابط کاربری تعاملی زیبا را خواهید دید که می‌توانید از طریق آن APIهای خود را تست کنید.
• ReDoc: به آدرس http://127.0.0.1:8000/redoc بروید. این رابط کاربری یک مستندات تمیز و کاربردی از API شما ارائه می‌دهد که برای مشاهده و مطالعه بسیار مناسب است.

پارامترهای مسیر (Path Parameters)

پارامترهای مسیر برای دریافت مقادیر خاص از URL استفاده می‌شوند. مثلاً، اگر بخواهید جزئیات یک کالا را با استفاده از ID آن دریافت کنید، ID کالا یک پارامتر مسیر است.

# main.py (ادامه)
from fastapi import FastAPI

app = FastAPI()

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

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

در اینجا:

• /items/{item_id}: {item_id} یک پارامتر مسیر است.
• item_id: int: با استفاده از تایپ‌هینتینگ پایتون، به FastAPI می‌گوییم که item_id باید یک عدد صحیح (integer) باشد. FastAPI به طور خودکار این اعتبارسنجی را انجام می‌دهد.

اگر به آدرس http://127.0.0.1:8000/items/5 بروید، پاسخ {"item_id": 5} را دریافت می‌کنید. اگر به http://127.0.0.1:8000/items/abc بروید، FastAPI به صورت خودکار یک خطای اعتبارسنجی 422 Unprocessable Entity برمی‌گرداند، چون “abc” یک عدد صحیح نیست.

پارامترهای کوئری (Query Parameters)

پارامترهای کوئری، جفت‌های کلید-مقدار هستند که پس از علامت سوال (?) در URL می‌آیند و با علامت & از هم جدا می‌شوند (مثلاً /items/?skip=0&limit=10). در FastAPI، اگر پارامتری در مسیر نباشد، به طور خودکار به عنوان پارامتر کوئری در نظر گرفته می‌شود.

# main.py (ادامه)
from fastapi import FastAPI, Query

app = FastAPI()

# ... (مسیرهای قبلی) ...

@app.get("/items/")
async def read_items(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

در این مثال:

• skip: int = 0 و limit: int = 10: اینها پارامترهای کوئری هستند که هم نوع (int) و هم مقدار پیش‌فرض دارند. اگر کاربر این پارامترها را در URL وارد نکند، مقادیر پیش‌فرض استفاده می‌شوند.

می‌توانید به آدرس http://127.0.0.1:8000/items/ (با مقادیر پیش‌فرض)، یا http://127.0.0.1:8000/items/?skip=20&limit=5 (با مقادیر دلخواه) دسترسی پیدا کنید.

درخواست بدنه (Request Body) با Pydantic

برای درخواست‌های POST، PUT و DELETE، اغلب نیاز داریم که داده‌ها را در “بدنه” (Body) درخواست از کلاینت دریافت کنیم. FastAPI برای این کار از Pydantic استفاده می‌کند که یک کتابخانه قدرتمند برای اعتبارسنجی و سریالایز کردن داده‌ها است.

# main.py (ادامه)
from fastapi import FastAPI
from pydantic import BaseModel
from typing import Optional

app = FastAPI()

# ... (مسیرهای قبلی) ...

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[float] = None

@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.dict()
    if item.tax:
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

در این مثال:

• class Item(BaseModel):: یک مدل داده با Pydantic تعریف می‌کنیم. این مدل ساختار داده‌هایی را که انتظار داریم در بدنه درخواست دریافت کنیم، مشخص می‌کند.
• name: str: فیلد name از نوع رشته و اجباری است.
• description: Optional[str] = None: فیلد description از نوع رشته و اختیاری است (Optional از ماژول typing).
• price: float: فیلد price از نوع عدد اعشاری و اجباری است.
• @app.post("/items/"): یک مسیر برای درخواست POST تعریف می‌کنیم.
• async def create_item(item: Item):: به FastAPI می‌گوییم که انتظار داریم بدنه درخواست از نوع Item باشد. FastAPI به طور خودکار JSON دریافتی را به یک نمونه از کلاس Item تبدیل و آن را اعتبارسنجی می‌کند.

حالا می‌توانید از طریق Swagger UI (http://127.0.0.1:8000/docs) این API را تست کنید. بخش /items/ را پیدا کنید، روی POST کلیک کنید و سپس Try it out را بزنید. می‌توانید یک JSON شبیه به این را در قسمت Request body وارد کنید:

{
  "name": "Foo",
  "description": "A very nice Item",
  "price": 35.4,
  "tax": 3.2
}

FastAPI به طور خودکار داده‌ها را پردازش و اعتبارسنجی می‌کند. اگر داده‌های ارسالی با مدل Item همخوانی نداشته باشند (مثلاً name را از نوع عدد بفرستید)، یک خطای 422 دریافت خواهید کرد.

اعتبارسنجی و مدیریت خطاها

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

# main.py (ادامه)
from fastapi import FastAPI, HTTPException

app = FastAPI()

# ... (مسیرهای قبلی و مدل Item) ...

items_db = {"foo": {"name": "Foo", "price": 50.2}}

@app.get("/items/{item_id}")
async def read_item_with_validation(item_id: str):
    if item_id not in items_db:
        raise HTTPException(status_code=404, detail="Item not found")
    return items_db[item_id]

@app.put("/items/{item_id}")
async def update_item(item_id: str, item: Item):
    if item_id not in items_db:
        raise HTTPException(status_code=404, detail="Item not found")
    items_db[item_id] = item.dict()
    return {"item_id": item_id, **item.dict()}

در این مثال:

• items_db: یک دیکشنری ساده به عنوان دیتابیس شبیه‌سازی شده ایجاد کرده‌ایم.
• raise HTTPException(...): اگر item_id در دیتابیس ما نباشد، یک HTTPException با کد وضعیت 404 (Not Found) و یک پیام detail مشخص برمی‌گردانیم. این کار باعث می‌شود کلاینت به جای یک خطای سرور عمومی، یک پیام خطای مشخص و استاندارد دریافت کند.

سیستم تزریق وابستگی (Dependency Injection)

یکی از قدرتمندترین ویژگی‌های FastAPI، سیستم Dependency Injection آن است. این سیستم به شما امکان می‌دهد تا وابستگی‌های (Dependencies) مشترک را در توابع کوچک و قابل استفاده مجدد تعریف کنید. این کار به تمیزی کد، کاهش تکرار و آسان‌تر شدن تست کمک می‌کند.

تصور کنید می‌خواهید یک سیستم احراز هویت ساده داشته باشید یا یک اتصال به پایگاه داده را برای چندین endpoint به اشتراک بگذارید.

# main.py (ادامه)
from fastapi import FastAPI, Depends, HTTPException, status

app = FastAPI()

# ... (مسیرهای قبلی) ...

async def common_parameters(q: Optional[str] = None, skip: int = 0, limit: int = 10):
    return {"q": q, "skip": skip, "limit": limit}

@app.get("/dependant-items/")
async def read_dependant_items(commons: dict = Depends(common_parameters)):
    return commons

# مثال پیشرفته‌تر: احراز هویت
async def get_current_user(token: str):
    if token != "mysecrettoken":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid authentication credentials",
            headers={"WWW-Authenticate": "Bearer"},
        )
    return {"username": "fastapi_user"}

@app.get("/users/me/")
async def read_users_me(current_user: dict = Depends(get_current_user)):
    return current_user

در این کد:

• async def common_parameters(...): یک تابع ساده است که دو پارامتر کوئری را دریافت می‌کند.
• commons: dict = Depends(common_parameters): با استفاده از Depends، FastAPI می‌فهمد که قبل از اجرای read_dependant_items، باید تابع common_parameters را اجرا کند و نتیجه آن را به عنوان پارامتر commons به تابع اصلی تزریق کند.
• get_current_user: یک تابع برای شبیه‌سازی احراز هویت. اگر توکن معتبر نباشد، یک HTTPException برمی‌گرداند.
• current_user: dict = Depends(get_current_user): هر مسیر که به این dependency نیاز داشته باشد، ابتدا توکن را بررسی می‌کند. اگر احراز هویت ناموفق باشد، خطای 401 برگردانده می‌شود و تابع اصلی مسیر حتی اجرا نمی‌شود.

سازماندهی کد با APIRouter

وقتی پروژه شما بزرگ می‌شود، قرار دادن همه مسیرها در یک فایل main.py باعث شلوغی و دشواری مدیریت کد می‌شود. APIRouter به شما اجازه می‌دهد تا مسیرهای مربوط به بخش‌های مختلف اپلیکیشن را در فایل‌های جداگانه سازماندهی کنید.

مثلاً، فرض کنید می‌خواهیم مسیرهای مربوط به کاربران (users) و کالاها (items) را جدا کنیم:

فایل `main.py`

# main.py
from fastapi import FastAPI
from .routers import items, users

app = FastAPI()

app.include_router(items.router, prefix="/items", tags=["items"])
app.include_router(users.router, prefix="/users", tags=["users"])

@app.get("/")
async def root():
    return {"message": "Welcome to the API!"}

دایرکتوری `routers` و فایل `items.py`

# routers/items.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/")
async def read_items():
    return [{"item_id": "Foo", "name": "Bar"}, {"item_id": "Baz", "name": "Qux"}]

@router.get("/{item_id}")
async def read_item(item_id: str):
    return {"item_id": item_id}

فایل `users.py`

# routers/users.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/")
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]

@router.get("/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id, "username": "fakeuser" + str(user_id)}

حالا می‌توانید به http://127.0.0.1:8000/items/ و http://127.0.0.1:8000/users/ دسترسی پیدا کنید. prefix مسیرها را در main.py مشخص می‌کند و tags به مستندات Swagger کمک می‌کند تا APIها را دسته‌بندی کند.

عملیات Asynchronous در FastAPI

پایتون از زمان نسخه 3.5، از async و await برای برنامه‌نویسی asynchronous پشتیبانی می‌کند. FastAPI به طور کامل از این قابلیت‌ها بهره می‌برد و این یکی از دلایل اصلی سرعت بالای آن است. توابع async def به سرور اجازه می‌دهند که در حین انتظار برای عملیات‌های کند (مانند خواندن از دیتابیس، درخواست شبکه، یا I/O فایل)، کارهای دیگری را انجام دهد. این به بهبود عملکرد و مقیاس‌پذیری API شما کمک می‌کند.

# main.py (مثال Async)
from fastapi import FastAPI
import asyncio

app = FastAPI()

@app.get("/async_data/")
async def get_async_data():
    # شبیه‌سازی یک عملیات I/O کند (مثلاً درخواست به یک API خارجی یا خواندن از دیتابیس)
    await asyncio.sleep(2) # 2 ثانیه انتظار
    return {"data": "This came from an async operation!"}

@app.get("/sync_data/")
def get_sync_data():
    # این تابع به صورت عادی اجرا می‌شود و اگر عملیات کندی داشته باشد،
    # می‌تواند event loop را بلاک کند (مگر اینکه Uvicorn آن را در تردپول اجرا کند)
    import time
    time.sleep(1) # 1 ثانیه انتظار (بلوک کننده)
    return {"data": "This came from a sync operation!"}

مقایسه FastAPI با سایر فریم‌ورک‌ها

پایتون فریم‌ورک‌های وب قدرتمند دیگری نیز دارد که هر کدام مزایا و معایب خود را دارند. در اینجا یک برسی مختصر و مقایسه‌ای با Flask و Django ارائه می‌دهیم:

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

ادغام با پایگاه داده

FastAPI به خودی خود شامل یک ORM (Object-Relational Mapper) داخلی نیست، اما این یک مزیت است؛ زیرا به شما اجازه می‌دهد از هر ORM یا کتابخانه پایگاه داده‌ای که ترجیح می‌دهید، استفاده کنید. محبوب‌ترین گزینه‌ها عبارتند از:

• SQLAlchemy: قدرتمندترین و انعطاف‌پذیرترین ORM برای پایتون است و با هر پایگاه داده SQL سازگار است. می‌توانید از نسخه‌های asynchronous آن (مانند SQLAlchemy 1.4 به بالا) در FastAPI به خوبی استفاده کنید.
• Tortoise ORM: یک ORM کاملاً asynchronous است که برای استفاده با فریم‌ورک‌های ASGI مانند FastAPI طراحی شده است.
• databases: یک کتابخانه سبک برای کار با پایگاه داده‌های SQL با پشتیبانی از async/await.
• PeeWee: یک ORM کوچک و سبک.

برای اتصال به دیتابیس معمولاً از سیستم Dependency Injection برای مدیریت سشن‌های دیتابیس (مانند db_session: Session = Depends(get_db)) استفاده می‌شود تا اتصال بهینه و ایمن باشد.

ملاحظات استقرار (Deployment)

وقتی آماده شدید تا API خود را به محیط پروداکشن منتقل کنید، چند نکته را باید در نظر بگیرید:

• Uvicorn Workers: در محیط پروداکشن، نباید فقط از یک نمونه Uvicorn استفاده کنید. برای بهره‌وری بیشتر از چند worker استفاده کنید. می‌توانید Uvicorn را مستقیماً با فلگ --workers اجرا کنید (مثلاً: uvicorn main:app --workers 4).
• Gunicorn + Uvicorn Workers: بهترین روش استقرار، استفاده از Gunicorn (یک WSGI HTTP Server) به عنوان مدیریت‌کننده فرآیند و Uvicorn به عنوان worker است. Gunicorn مدیریت فرآیندها، لاگین و دیگر کارهای مدیریتی را انجام می‌دهد، در حالی که Uvicorn درخواست‌های ASGI را هندل می‌کند.

gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

• Docker: استفاده از داکر برای پکیج کردن اپلیکیشن شما در یک کانتینر، فرآیند استقرار را بسیار ساده‌تر و قابل تکرار می‌کند.
• Reverse Proxy: در محیط پروداکشن، همیشه توصیه می‌شود از یک reverse proxy مانند Nginx یا Caddy در جلوی اپلیکیشن FastAPI خود استفاده کنید. این کار به مدیریت SSL/TLS، کشینگ، لود بالانسینگ و امنیت کمک می‌کند.
• HTTPS: همیشه از HTTPS برای امن کردن ارتباطات API خود استفده کنید.

موارد استفاده واقعی FastAPI

FastAPI به دلیل سرعت، کارایی و ویژگی‌های مدرنش، در سناریوهای مختلفی مورد استفاده قرار می‌گیرد:

• ساخت Microservices: به دلیل سبک بودن و سرعت بالا، برای ساخت Microservices که نیاز به پردازش حجم زیادی از درخواست‌ها دارند، ایده‌آل است.
• APIهای یادگیری ماشین (Machine Learning APIs): با توجه به نیاز به پردازش سریع و اعتبارسنجی داده، FastAPI برای سرویس‌دهی به مدل‌های یادگیری ماشین و APIهای مربوط به دیتا ساینس بسیار محبوب است.
• بک‌اند وب (Web Backends): می‌تواند به عنوان بک‌اند برای هر نوع فرانت‌اندی (SPA، موبایل و غیره) عمل کند.
• سیستم‌های Real-time: با پشتیبانی از WebSocketها (از طریق Starlette)، برای ساخت اپلیکیشن‌های Real-time مثل چت یا داشبوردهای live مناسب است.
• پروژه‌های High-performance: در مواردی که به پاسخگویی سریع و توان عملیاتی بالا نیاز است.

عیب‌یابی سریع (Troubleshooting)

در حین کار با FastAPI، ممکن است با چند مشکل رایج روبرو شوید. در اینجا چند راه‌حل برای آنها آورده شده است:

• `ModuleNotFoundError: No module named ‘fastapi’` یا `’uvicorn’`

  راه‌حل: مطمئن شوید که FastAPI و Uvicorn در محیط مجازی فعال شما نصب شده‌اند. دوباره دستور pip install fastapi "uvicorn[standard]" را در محیط فعال اجرا کنید.

• خطای 422 Unprocessable Entity

  راه‌حل: این خطا معمولاً به دلیل عدم تطابق داده‌های ارسالی با مدل Pydantic شماست. مستندات Swagger UI را چک کنید تا ببینید API چه ساختاری از داده را انتظار دارد. مطمئن شوید که نوع داده‌ها و اجباری/اختیاری بودن فیلدها را رعایت کرده‌اید.

• `TypeError: ‘int’ object is not awaitable` یا شبیه به آن

  راه‌حل: این خطا زمانی رخ می‌دهد که شما سعی می‌کنید روی یک تابع یا شیء عادی از await استفاده کنید. مطمئن شوید توابعی که با await فراخوانی می‌کنید، با async def تعریف شده‌اند.

• `uvicorn.workers.UvicornWorker` – `ImportError: cannot import name ‘ASGICycle’ from ‘uvicorn.protocols.http.h11_protocol’`

  راه‌حل: این خطا ممکن است به دلیل نسخه ناسازگار Uvicorn با Starlette یا FastAPI باشد. معمولاً با به‌روزرسانی uvicorn به آخرین نسخه حل می‌شود: pip install --upgrade uvicorn.

• API شما در مرورگر نشان داده نمی‌شود (مثلاً خطای `connection refused`)

  راه‌حل: مطمئن شوید Uvicorn در حال اجراست و هیچ فایروالی پورت 8000 (یا پورتی که استفاده می‌کنید) را مسدود نکرده است. همچنین، بررسی کنید که آیا اپلیکیشن FastAPI شما به درستی نامگذاری شده و در دستور `uvicorn main:app` به درستی ارجاع داده شده است.

پرسش‌های متداول (FAQ)

جمع‌بندی

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

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