مقدمه ای بر FastAPI

معرفی

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

FastAPI ساخته شده است روی Starlette (برای بخش‌های وب) و Pydantic (برای بخش‌های داده)، به آن اجازه می‌دهد تا ویژگی‌های کاملاً قانع‌کننده‌ای را ارائه دهد. به لطف Pydantic دارای تجزیه درخواست سریع و اعتبارسنجی مدل است. همچنین از مدرن، پایتونیک پشتیبانی می کند async def سینتکس برای کارهای ناهمزمان و ویژگی های امنیتی و احراز هویت قوی را ارائه می دهد. علاوه بر این، FastAPI اسناد API تعاملی خودکار را فراهم می کند، به شما و تیم شما اجازه می دهد تا به سرعت API خود را درک کرده و آزمایش کنید.

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

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

نصب و راه اندازی

برای کار با FastAPI، ابتدا به یک محیط پایتون کاربردی نیاز دارید. اگر قبلا این کار را نکرده اید، آخرین نسخه پایتون را از وب سایت رسمی دانلود و نصب کنید. از زمان نگارش این مقاله، پایتون 3.9 یا جدیدتر برای بهره مندی از تمام مزایایی که FastAPI ارائه می دهد، توصیه می شود.

FastAPI در دسترس است روی ایندکس بسته پایتون (PyPI) و قابل نصب است pip، مدیر بسته پیش فرض پایتون. شما هم باید نصب کنید uvicorn، یک سرور ASGI، برای ارائه برنامه FastAPI شما:

$ pip install fastapi
$ pip install uvicorn

راه اندازی یک پروژه FastAPI جدید

پس از نصب FastAPI و uvicorn، آماده شروع پروژه جدید FastAPI خود هستید. با ایجاد یک دایرکتوری جدید برای پروژه خود شروع کنید:

$ mkdir fastapi-project
$ cd fastapi-project

در دایرکتوری پروژه، یک فایل پایتون جدید مانند main.py. این به عنوان نقطه ورود برای برنامه FastAPI شما عمل می کند. در اینجا اساسی ترین برنامه FastAPI ممکن است:

from fastapi import FastAPI

app = FastAPI()

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

این اسکریپت یک برنامه جدید FastAPI ایجاد می کند و یک مسیر واحد را تعریف می کند. /، که درخواست های GET را می پذیرد و یک پاسخ ساده JSON را برمی گرداند.

اجرای برنامه FastAPI شما

برای اجرای برنامه FastAPI خود، از uvicorn دستور به دنبال آن نام ماژول شما (فایل پایتون بدون .py پسوند)، و متغیری که برنامه FastAPI شما است:

$ uvicorn main:app --reload

را --reload flag بارگذاری مجدد داغ را فعال می کند، به این معنی که هر زمان که شما تغییراتی در فایل های پایتون خود ایجاد کنید، سرور به طور خودکار به روز می شود.

هدایت به http://localhost:8000 در مرورگر وب خود، و باید پاسخ JSON را از برنامه FastAPI خود مشاهده کنید: {"Hello": "World"}.

تور مختصری از یک برنامه FastAPI

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

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

مبانی FastAPI

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

تعریف نقاط پایانی

در FastAPI، نقطه پایانی به عنوان یک تابع پایتون که با یک تزئین کننده مسیر تزئین شده است، تعریف می شود. دکوراتور مسیر مانند @app.get()، روش و مسیر HTTP را برای نقطه پایانی مشخص می کند:

from fastapi import FastAPI

app = FastAPI()

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

این یک نقطه پایانی GET در مسیر تعریف می کند /items/{item_id}، جایی که {item_id} یک پارامتر مسیر است. کارکرد read_item() هر زمان که درخواستی به این نقطه پایانی ارسال شود، فراخوانی می شود.

پارامترهای مسیر و پارامترهای پرس و جو

در مثال قبلی، پارامتر مسیر item_id به طور خودکار به عنوان یک عدد صحیح تفسیر می شود : int حاشیه نویسی را تایپ کنید FastAPI تأیید می کند که این پارامتر یک عدد صحیح است و قبل از ارسال آن به تابع شما، آن را از یک رشته تبدیل می کند.

پارامترهای پرس و جو به عنوان پارامترهای تابع تعریف می شوند. به عنوان مثال، برای افزودن یک پارامتر پرس و جو q، می توانید آن را اصلاح کنید read_item() عملکرد به شرح زیر است:

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

اینجا q یک پارامتر پرس و جو اختیاری با مقدار پیش فرض است None.

درخواست بدن

برای تعریف الف نقطه پایانی POST که بدنه درخواستی را می پذیرد، می توانید از مدل های Pydantic استفاده کنید. یک مدل Pydantic یک کلاس پایتون است که گسترش می یابد pydantic.BaseModel و مجموعه ای از ویژگی ها را تعریف می کند که هر کدام دارای یک نوع حاشیه نویسی هستند:

from pydantic import BaseModel

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

@app.post("/items/")
def create_item(item: Item):
    return item

در این مثال، create_item() تابع یک پارامتر را می پذیرد، item، که انتظار می رود نمونه ای از این باشد Item مدل. FastAPI به طور خودکار بدنه درخواست را تأیید می کند تا مطمئن شود که با مدل مطابقت دارد، JSON را به یک تبدیل می کند Item نمونه، و این نمونه را به تابع خود منتقل کنید.

نهادهای پاسخگو

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

@app.get("/ping")
def ping():
    return "pong"

در اینجا، رشته “pong” به عنوان یک پاسخ JSON برگردانده می شود ("pong").

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

موضوعات پیشرفته در FastAPI

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

استفاده از مدل های Pydantic برای اعتبار سنجی و سریال سازی داده ها

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

from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str = Field(..., example="Foo")
    description: str = Field(None, example="A very nice Item")
    price: float = Field(..., example=35.4)
    tax: float = Field(None, example=3.2)

@app.post("/items/")
def create_item(item: Item):
    return item

را Field تابع برای افزودن اعتبار اضافی به فیلدهای مدل Pydantic و ارائه مقادیر نمونه استفاده می شود.

رسیدگی به خطاها و استثنائات

FastAPI راهی برای رسیدگی به خطاها و استثناها به صورت یکپارچه فراهم می کند. شما می توانید استفاده کنید HTTPException برای برگرداندن پاسخ های خطای HTTP:

from fastapi import HTTPException

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

تزریق وابستگی

FastAPI یک سیستم تزریق وابستگی ساده اما قدرتمند دارد. مبتنی است روی حاشیه نویسی از نوع پایتون و نیازی به پیکربندی پیچیده ندارد:

from fastapi import Depends

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

@app.get("/items/{item_id}")
def read_item(item_id: int, db = Depends(get_db)):
    item = db.get(item_id)
    return item

امنیت و احراز هویت

FastAPI چندین ابزار امنیتی را در جعبه فراهم می کند، مانند OAuth2 با توکن های JWT و هش کردن:

from fastapi import Depends, FastAPI, HTTPException
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

@app.get("/items/{item_id}")
async def read_item(token: str = Depends(oauth2_scheme)):
    return {"token": token}

در این مثال، OAuth2PasswordBearer کلاس برای مدیریت OAuth2 استفاده می شود. را /items/{item_id} نقطه پایانی نیاز به یک Authorization هدر با توکن حامل.

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

FastAPI دیکته نمی کند که از کدام پایگاه داده استفاده کنید و می تواند با هر مشتری ORM یا DB استفاده شود:

from fastapi import Depends, FastAPI
from sqlalchemy.orm import Session

from . import crud, models, schemas
from .database import SessionLocal, engine

app = FastAPI()

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

@app.post("/users/", response_model=schemas.User)
def create_user(user: schemas.UserCreate, db: Session = Depends(get_db)):
    db_user = crud.get_user_by_email(db, email=user.email)
    ...

این مثال استفاده می کند SQLAlchemy برای تعامل با پایگاه داده را get_db وابستگی یک جلسه پایگاه داده برای هر درخواست فراهم می کند و با پایان درخواست آن را می بندد.

تست واحد در FastAPI

برنامه های FastAPI را می توان به راحتی با آن آزمایش کرد TestClient از جانب fastapi.testclient:

from fastapi.testclient import TestClient

def test_read_item():
    client = TestClient(app)
    response = client.get("/items/42")
    assert response.status_code == 200
    assert response.json() == {"item_id": 42}

این یک تست اساسی است که یک درخواست GET را به آن ارسال می کند /items/42 نقطه پایانی و ادعا می کند که کد وضعیت پاسخ 200 و بدنه پاسخ است {"item_id": 42}.

در بخش بعدی، ما این مفاهیم را در یک برنامه دنیای واقعی به کار خواهیم برد، و به شما نشان خواهیم داد که چگونه یک برنامه CRUD اولیه با FastAPI بسازید.

برنامه دنیای واقعی

در این بخش، ما از تمام مفاهیمی که تاکنون یاد گرفته‌ایم برای ایجاد یک برنامه کاربردی در دنیای واقعی استفاده می‌کنیم: یک CRUD (ایجاد، خواندن، به‌روزرسانی، حذف) API برای یک کتابفروشی فرضی. این برنامه به ما امکان می‌دهد کتاب‌هایی را در فهرست موجودی فروشگاه ایجاد، بازیابی، به‌روزرسانی و حذف کنیم.

مرحله 1 – راه اندازی پروژه شما

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

مرحله 2 – تعریف مدل داده

ما با تعریف یک مدل داده برای کتاب‌های موجود در فروشگاه خود شروع می‌کنیم. برای این کار از Pydantic استفاده می کنیم BaseModel کلاس

from pydantic import BaseModel

class Book(BaseModel):
    name: str
    author: str
    isbn: str

مرحله 3 – راه اندازی پایگاه داده در حافظه

در مرحله بعد، بیایید یک پایگاه داده در حافظه برای API خود راه اندازی کنیم. ما از یک فرهنگ لغت ساده پایتون برای ذخیره داده های خود استفاده خواهیم کرد:

books_db = {}

مرحله 4 – تعیین نقاط پایانی API

اکنون می توانیم نقاط پایانی را برای API خود تعریف کنیم.

به یک کتاب ایجاد کنید، در مسیر به یک نقطه پایانی POST نیاز داریم /books:

@app.post("/books/")
def create_book(book: Book):
    if book.isbn in books_db:
        raise HTTPException(status_code=400, detail="ISBN already exists")
    books_db(book.isbn) = book.dict()
    return books_db(book.isbn)

به یک کتاب را بازیابی کنید، در مسیر به یک نقطه پایانی GET نیاز داریم /books/{isbn}:

@app.get("/books/{isbn}")
def read_book(isbn: str):
    if isbn not in books_db:
        raise HTTPException(status_code=404, detail="Book not found")
    return books_db(isbn)

ما به یک نقطه پایانی PUT در مسیر نیاز داریم /books/{isbn} به یک کتاب را به روز کنید:

@app.put("/books/{isbn}")
def update_book(isbn: str, book: Book):
    if isbn not in books_db:
        raise HTTPException(status_code=404, detail="Book not found")
    books_db(isbn) = book.dict()
    return books_db(isbn)

به یک کتاب را حذف کنید، در مسیر به یک نقطه پایانی DELETE نیاز داریم /books/{isbn}.

@app.delete("/books/{isbn}")
def delete_book(isbn: str):
    if isbn not in books_db:
        raise HTTPException(status_code=404, detail="Book not found")
    del books_db(isbn)
    return {"message": "Book deleted successfully!"}

با استفاده از FastAPI، در کمترین زمان یک API CRUD ایجاد کرده اید. اکنون یک برنامه کاربردی دارید که آماده استقرار و استفاده است.

اکوسیستم FastAPI

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

SQLModel

SQLModel کتابخانه ای برای تعامل با پایگاه های داده SQL با استفاده از مدل های پایتون است. ساخته شده است روی بالای SQLAlchemy و Pydantic است و برای کار با FastAPI طراحی شده است. اگر برنامه شما از پایگاه داده SQL استفاده می کند، SQLModel می تواند تعریف مدل های داده شما و انجام عملیات پایگاه داده را آسان تر کند.

کاربران FastAPI

کاربران FastAPI کتابخانه ای است که ویژگی های رایج مدیریت کاربر را برای برنامه های FastAPI مانند ثبت نام کاربر، ورود به سیستم، تنظیم مجدد رمز عبور و تأیید ایمیل ارائه می دهد. از انواع روش های احراز هویت از جمله JWT، OAuth2 و HTTP Basic Auth پشتیبانی می کند.

مجوزهای FastAPI

مجوزهای FastAPI یک کتابخانه ساده و موثر برای مدیریت مجوزها و نقش ها در یک برنامه FastAPI است. این به شما امکان می دهد مجوزها را به صورت اعلامی تعریف کنید و به طور خودکار آنها را برای هر درخواست بررسی می کند.

ابزارهای FastAPI

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

تایپر

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

استارلت

FastAPI ساخته شده است روی بالای استارلتیک چارچوب سبک وزن ASGI. در حالی که FastAPI یک API سطح بالا برای ساخت برنامه های کاربردی وب ارائه می دهد، Starlette ابزارهای اساسی را برای رسیدگی به درخواست ها و پاسخ های HTTP، مسیریابی، سوکت های وب و موارد دیگر ارائه می دهد. درک Starlette می تواند به شما درک عمیق تری از FastAPI و روش عملکرد آن بدهد.

همه این ابزارها و کتابخانه ها می توانند برنامه های FastAPI شما را بهبود بخشند و آنها را قدرتمندتر، انعطاف پذیرتر و قوی تر کنند. با درک اکوسیستم FastAPI، می توانید از FastAPI و همه چیزهایی که ارائه می دهد نهایت استفاده را ببرید.

نتیجه

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

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

در ساخت یک برنامه CRUD، ما دیدیم که چگونه همه این مؤلفه ها در یک سناریوی واقعی کنار هم قرار می گیرند. پیروی از بهترین شیوه ها، قابلیت نگهداری و مقیاس پذیری برنامه های ما را تضمین می کند.

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

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