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

فهرست مطالب

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

FastAPI در یک نگاه

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "سلام دنیا!"}

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}

uvicorn main:app --reload

@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

@app.get("/users/me") # این مسیر باید قبل از /users/{user_id} باشد
async def read_user_me():
    return {"user_id": "current user"}

@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

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

from typing import Optional

@app.get("/products/")
async def read_products(name: str, price: Optional[float] = None):
    results = {"name": name}
    if price:
        results.update({"price": price})
    return results

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

from fastapi import FastAPI, Query, Path
from pydantic import BaseModel, Field

app = FastAPI()

class UserIn(BaseModel):
    username: str = Field(min_length=3, max_length=20)
    email: str = Field(pattern=r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}$")
    password: str = Field(min_length=8)

@app.post("/users/")
async def create_user(user: UserIn):
    return user

@app.get("/search/")
async def search_items(
    q: str = Query(..., min_length=3, max_length=50, title="Search Query", description="Search string for items")
):
    results = {"query": q}
    return results

from fastapi import FastAPI, HTTPException

app = FastAPI()

fake_items_db = {"foo": {"name": "Foo"}, "bar": {"name": "Bar"}}

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

from fastapi import FastAPI, Depends, HTTPException, status

app = FastAPI()

async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
    return {"q": q, "skip": skip, "limit": limit}

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

from fastapi.security import OAuth2PasswordBearer
from fastapi import Header

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

async def get_current_user(token: str = Depends(oauth2_scheme)):
    # در اینجا باید توکن را اعتبارسنجی کنید
    # و کاربر مربوطه را برگردانید
    if token != "fake-super-secret-token":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid authentication credentials",
            headers={"WWW-Authenticate": "Bearer"},
        )
    return {"username": "currentuser", "token": token}

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

from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from jose import JWTError, jwt
from passlib.context import CryptContext
from datetime import datetime, timedelta

# این مقادیر را باید از متغیرهای محیطی یا فایل پیکربندی بخوانید
SECRET_KEY = "your-secret-key"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

# توابع کمکی برای JWT
def create_access_token(data: dict, expires_delta: timedelta | None = None):
    to_encode = data.copy()
    if expires_delta:
        expire = datetime.utcnow() + expires_delta
    else:
        expire = datetime.utcnow() + timedelta(minutes=15)
    to_encode.update({"exp": expire})
    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
    return encoded_jwt

def verify_password(plain_password, hashed_password):
    return pwd_context.verify(plain_password, hashed_password)

def get_password_hash(password):
    return pwd_context.hash(password)

# دیتابیس کاربران فرضی
fake_users_db = {
    "john.doe": {
        "username": "john.doe",
        "hashed_password": get_password_hash("secret"),
        "email": "john@example.com",
        "full_name": "John Doe"
    }
}

def authenticate_user(username: str, password: str):
    user = fake_users_db.get(username)
    if not user or not verify_password(password, user["hashed_password"]):
        return False
    return user

async def get_current_active_user(token: str = Depends(oauth2_scheme)):
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str = payload.get("sub")
        if username is None:
            raise credentials_exception
    except JWTError:
        raise credentials_exception
    user = fake_users_db.get(username) # در یک برنامه واقعی از دیتابیس می‌خوانید
    if user is None:
        raise credentials_exception
    return user

app = FastAPI()

@app.post("/token")
async def login_for_access_token(form_data: OAuth2PasswordRequestForm = Depends()):
    user = authenticate_user(form_data.username, form_data.password)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
            headers={"WWW-Authenticate": "Bearer"},
        )
    access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    access_token = create_access_token(
        data={"sub": user["username"]}, expires_delta=access_token_expires
    )
    return {"access_token": access_token, "token_type": "bearer"}

@app.get("/users/me/", response_model=dict) # یک مدل پاسخ Pydantic واقعی بهتر است
async def read_users_me(current_user: dict = Depends(get_current_active_user)):
    return current_user

.
├── main.py
├── routers/
│   ├── __init__.py
│   ├── items.py
│   └── users.py
└── models/
    ├── __init__.py
    └── item.py
    └── user.py

from fastapi import APIRouter

router = APIRouter()

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

@router.post("/items/")
async def create_item():
    return {"message": "Item created"}

from fastapi import FastAPI
from routers import items, users # فرض کنید routers/users.py هم شبیه items.py است

app = FastAPI()

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

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

pip install gunicorn

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

# Dockerfile
FROM python:3.9-slim-buster

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
# برای محیط پروداکشن:
# CMD ["gunicorn", "main:app", "--workers", "4", "--worker-class", "uvicorn.workers.UvicornWorker", "--bind", "0.0.0.0:8000"]

مشکلات رایج و راه‌حل‌ها

• ۱. خطای ۴۲۲ Unprocessable Entity

  علت: این خطا معمولاً به دلیل عدم تطابق داده‌های ارسالی با مدل Pydantic یا تایپ‌هینت‌های تعریف شده در تابع است. مثلاً ارسال رشته به جای عدد، یا از قلم افتادن یک فیلد اجباری.

  راه‌حل: پیام خطا را در پاسخ API با دقت بخوانید. FastAPI و Pydantic اطلاعات دقیقی درباره اینکه کدام فیلد مشکل دارد و چرا، ارائه می‌دهند. مستندات Swagger UI (/docs) نیز به شما کمک می‌کند تا ساختار صحیح Request Body را ببینید.

• ۲. Uvicorn اجرا نمی‌شود یا خطای “Application startup failed” می‌دهد.

  علت: ممکن است در فایل main.py (یا هر فایل دیگری که app را تعریف کرده‌اید) خطای سینتکسی یا منطقی داشته باشید. همچنین، اطمینان حاصل کنید که نام فایل و نام متغیر app را در دستور uvicorn به درستی وارد کرده‌اید (مثلاً main:app).

  راه‌حل: خطاهای نمایش داده شده در ترمینال را بررسی کنید. اغلب اوقات، پایتون مسیر و شماره خط خطا را مشخص می‌کند. کد خود را برای یافتن مشکلات سینتکسی یا ایمپورت‌های ناموفق (import) چک کنید.

• ۳. وابستگی‌ها (Dependencies) به درستی تزریق نمی‌شوند یا خطای Circular Dependency.

  علت: گاهی اوقات توابع وابسته به یکدیگر نیاز دارند که منجر به یک حلقه (loop) می‌شود. همچنین ممکن است تایپ‌هینت‌ها به درستی تعریف نشده باشند.

  راه‌حل: ساختار وابستگی‌های خود را بازبینی کنید تا از ایجاد حلقه‌های وابستگی جلوگیری شود. از Depends() به درستی استفاده کنید و مطمئن شوید که توابع وابستگی نیز تایپ‌هینت‌های صحیح دارند. برای حل مشکلات مربوط به وارد کردن ماژول‌ها در ساختار پروژه بزرگتر، از from __future__ import annotations در بالای فایل‌ها استفاده کنید تا مشکل Cyclic Imports حل شود.

• ۴. مسیرهای API (Endpoints) در Swagger UI ظاهر نمی‌شوند.

  علت: این می‌تواند به دلیل عدم تعریف صحیح app.include_router() یا عدم فراخوانی app = FastAPI() باشد. اگر از APIRouter استفاده می‌کنید، مطمئن شوید که routerهای خود را در main.py به app اصلی اضافه کرده‌اید.

  راه‌حل: فایل main.py را بررسی کنید و از اینکه همه routerها با app.include_router() به درستی اضافه شده‌اند، اطمینان حاصل کنید. همچنین، اگر متد HTTP (مثلاً @app.post یا @router.get) را فراموش کرده باشید، مسیر نمایش داده نمی‌شود.