# FastAPI
فریم‌ورک FastAPI، کارایی بالا، یادگیری آسان، کدنویسی سریع، آماده برای استفاده در محیط پروداکشن
---
**مستندات**: https://fastapi.tiangolo.com
**کد منبع**: https://github.com/fastapi/fastapi
---
FastAPI یک وب فریم‌ورک مدرن و سریع (با کارایی بالا) برای ایجاد APIهای متنوع (وب، وب‌سوکت و غبره) با زبان پایتون نسخه +۳.۶ است. این فریم‌ورک با رعایت کامل راهنمای نوع داده (Type Hint) ایجاد شده است.
ویژگی‌های کلیدی این فریم‌ورک عبارتند از:
* **سرعت**: کارایی بسیار بالا و قابل مقایسه با **NodeJS** و **Go** (با تشکر از Starlette و Pydantic). [یکی از سریع‌ترین فریم‌ورک‌های پایتونی موجود](#_10).
* **کدنویسی سریع**: افزایش ۲۰۰ تا ۳۰۰ درصدی سرعت توسعه قابلیت‌های جدید. *
* **باگ کمتر**: کاهش ۴۰ درصدی خطاهای انسانی (برنامه‌نویسی). *
* **هوشمندانه**: پشتیبانی فوق‌العاده در محیط‌های توسعه یکپارچه (IDE). تکمیل در همه بخش‌های کد. کاهش زمان رفع باگ.
* **آسان**: طراحی شده برای یادگیری و استفاده آسان. کاهش زمان مورد نیاز برای مراجعه به مستندات.
* **کوچک**: کاهش تکرار در کد. چندین قابلیت برای هر پارامتر (منظور پارامترهای ورودی تابع هندلر می‌باشد، به بخش خلاصه در همین صفحه مراجعه شود). باگ کمتر.
* **استوار**: ایجاد کدی آماده برای استفاده در محیط پروداکشن و تولید خودکار مستندات تعاملی
* **مبتنی بر استانداردها**: مبتنی بر (و منطبق با) استانداردهای متن باز مربوط به API: OpenAPI (سوگر سابق) و JSON Schema.
* تخمین‌ها بر اساس تست‌های انجام شده در یک تیم توسعه داخلی که مشغول ایجاد برنامه‌های کاربردی واقعی بودند صورت گرفته است.
## اسپانسرهای طلایی
{% if sponsors %}
{% for sponsor in sponsors.gold -%}
{% endfor %}
{% endif %}
دیگر اسپانسرها
## نظر دیگران در مورد FastAPI
[...] I'm using FastAPI a ton these days. [...] I'm actually planning to use it for all of my team's ML services at Microsoft. Some of them are getting integrated into the core Windows product and some Office products."
Kabir Khan -
Microsoft (ref)"We adopted the FastAPI library to spawn a RESTserver that can be queried to obtain predictions. [for Ludwig]"
Piero Molino, Yaroslav Dudin, and Sai Sumanth Miryala -
Uber (ref)"Netflix is pleased to announce the open-source release of our crisis management orchestration framework: Dispatch! [built with FastAPI]"
Kevin Glisson, Marc Vilanova, Forest Monsen -
Netflix (ref)"I’m over the moon excited about FastAPI. It’s so fun!"
---
"Honestly, what you've built looks super solid and polished. In many ways, it's what I wanted Hug to be - it's really inspiring to see someone build that."
---
"If you're looking to learn one modern framework for building REST APIs, check out FastAPI [...] It's fast, easy to use and easy to learn [...]"
"We've switched over to FastAPI for our APIs [...] I think you'll like it [...]"
---
## **Typer**, فریم‌ورکی معادل FastAPI برای کار با واسط خط فرمان
اگر در حال ساختن برنامه‌ای برای استفاده در CLI (به جای استفاده در وب) هستید، می‌توانید از **Typer**. استفاده کنید.
**Typer** دوقلوی کوچکتر FastAPI است و قرار است معادلی برای FastAPI در برنامه‌های CLI باشد.️ 🚀
## نیازمندی‌ها
پایتون +۳.۶
FastAPI مبتنی بر ابزارهای قدرتمند زیر است:
* فریم‌ورک Starlette برای بخش وب.
* کتابخانه Pydantic برای بخش داده.
## نصب
```console
$ pip install fastapi
---> 100%
```
نصب یک سرور پروداکشن نظیر Uvicorn یا Hypercorn نیز جزء نیازمندی‌هاست.
```console
$ pip install "uvicorn[standard]"
---> 100%
```
## مثال
### ایجاد کنید
* فایلی به نام `main.py` با محتوای زیر ایجاد کنید:
```Python
from typing import Union
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"Hello": "World"}
@app.get("/items/{item_id}")
def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
```
همچنین می‌توانید از async def... نیز استفاده کنید
اگر در کدتان از `async` / `await` استفاده می‌کنید، از `async def` برای تعریف تابع خود استفاده کنید:
```Python hl_lines="9 14"
from typing import Optional
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def read_root():
return {"Hello": "World"}
@app.get("/items/{item_id}")
async def read_item(item_id: int, q: Optional[str] = None):
return {"item_id": item_id, "q": q}
```
**توجه**:
اگر با `async / await` آشنا نیستید، به بخش _"عجله دارید?"_ در صفحه درباره `async` و `await` در مستندات مراجعه کنید.
### اجرا کنید
با استفاده از دستور زیر سرور را اجرا کنید:
```console
$ uvicorn main:app --reload
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [28720]
INFO: Started server process [28722]
INFO: Waiting for application startup.
INFO: Application startup complete.
```
درباره دستور uvicorn main:app --reload...
دستور `uvicorn main:app` شامل موارد زیر است:
* `main`: فایل `main.py` (ماژول پایتون ایجاد شده).
* `app`: شیء ایجاد شده در فایل `main.py` در خط `app = FastAPI()`.
* `--reload`: ریستارت کردن سرور با تغییر کد. تنها در هنگام توسعه از این گزینه استفاده شود..
### بررسی کنید
آدرس http://127.0.0.1:8000/items/5?q=somequery را در مرورگر خود باز کنید.
پاسخ JSON زیر را مشاهده خواهید کرد:
```JSON
{"item_id": 5, "q": "somequery"}
```
تا اینجا شما APIای ساختید که:
* درخواست‌های HTTP به _مسیرهای_ `/` و `/items/{item_id}` را دریافت می‌کند.
* هردو _مسیر_ عملیات (یا HTTP _متد_) `GET` را پشتیبانی می‌کند.
* _مسیر_ `/items/{item_id}` شامل _پارامتر مسیر_ `item_id` از نوع `int` است.
* _مسیر_ `/items/{item_id}` شامل _پارامتر پرسمان_ اختیاری `q` از نوع `str` است.
### مستندات API تعاملی
حال به آدرس http://127.0.0.1:8000/docs بروید.
مستندات API تعاملی (ایجاد شده به کمک Swagger UI) را مشاهده خواهید کرد:
### مستندات API جایگزین
حال به آدرس http://127.0.0.1:8000/redoc بروید.
مستندات خودکار دیگری را مشاهده خواهید کرد که به کمک ReDoc ایجاد می‌شود:
## تغییر مثال
حال فایل `main.py` را مطابق زیر ویرایش کنید تا بتوانید بدنه یک درخواست `PUT` را دریافت کنید.
به کمک Pydantic بدنه درخواست را با انواع استاندارد پایتون تعریف کنید.
```Python hl_lines="4 9-12 25-27"
from typing import Optional
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
price: float
is_offer: Union[bool, None] = None
@app.get("/")
def read_root():
return {"Hello": "World"}
@app.get("/items/{item_id}")
def read_item(item_id: int, q: Union[str, None] = None):
return {"item_id": item_id, "q": q}
@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
return {"item_name": item.name, "item_id": item_id}
```
سرور به صورت خودکار ری‌استارت می‌شود (زیرا پیشتر از گزینه `--reload` در دستور `uvicorn` استفاده کردیم).
### تغییر مستندات API تعاملی
مجددا به آدرس http://127.0.0.1:8000/docs بروید.
* مستندات API تعاملی به صورت خودکار به‌روز شده است و شامل بدنه تعریف شده در مرحله قبل است:
* روی دکمه "Try it out" کلیک کنید، اکنون می‌توانید پارامترهای مورد نیاز هر API را مشخص کرده و به صورت مستقیم با آنها تعامل کنید:
* سپس روی دکمه "Execute" کلیک کنید، خواهید دید که واسط کاربری با APIهای تعریف شده ارتباط برقرار کرده، پارامترهای مورد نیاز را به آنها ارسال می‌کند، سپس نتایج را دریافت کرده و در صفحه نشان می‌دهد:
### تغییر مستندات API جایگزین
حال به آدرس http://127.0.0.1:8000/redoc بروید.
* خواهید دید که مستندات جایگزین نیز به‌روزرسانی شده و شامل پارامتر پرسمان و بدنه تعریف شده می‌باشد:
### خلاصه
به طور خلاصه شما **یک بار** انواع پارامترها، بدنه و غیره را به عنوان پارامترهای ورودی تابع خود تعریف می‌کنید.
این کار را با استفاده از انواع استاندارد و مدرن موجود در پایتون انجام می‌دهید.
نیازی به یادگیری نحو جدید یا متدها و کلاس‌های یک کتابخانه بخصوص و غیره نیست.
تنها **پایتون +۳.۶**.
به عنوان مثال برای یک پارامتر از نوع `int`:
```Python
item_id: int
```
یا برای یک مدل پیچیده‌تر مثل `Item`:
```Python
item: Item
```
...و با همین اعلان تمامی قابلیت‌های زیر در دسترس قرار می‌گیرد:
* پشتیبانی ویرایشگر متنی شامل:
* تکمیل کد.
* بررسی انواع داده.
* اعتبارسنجی داده:
* خطاهای خودکار و مشخص در هنگام نامعتبر بودن داده.
* اعتبارسنجی، حتی برای اشیاء JSON تو در تو.
* تبدیل داده ورودی: که از شبکه رسیده به انواع و داده پایتونی. این داده شامل:
* JSON.
* پارامترهای مسیر.
* پارامترهای پرسمان.
* کوکی‌ها.
* سرآیند‌ها (هدرها).
* فرم‌ها.
* فایل‌ها.
* تبدیل داده خروجی: تبدیل از انواع و داده پایتون به داده شبکه (مانند JSON):
* تبدیل انواع داده پایتونی (`str`, `int`, `float`, `bool`, `list` و غیره).
* اشیاء `datetime`.
* اشیاء `UUID`.
* qمدل‌های پایگاه‌داده.
* و موارد بیشمار دیگر.
* دو مدل مستند API تعاملی خودکار :
* Swagger UI.
* ReDoc.
---
به مثال قبلی باز می‌گردیم، در این مثال **FastAPI** موارد زیر را انجام می‌دهد:
* اعتبارسنجی اینکه پارامتر `item_id` در مسیر درخواست‌های `GET` و `PUT` موجود است.
* اعتبارسنجی اینکه پارامتر `item_id` در درخواست‌های `GET` و `PUT` از نوع `int` است.
* اگر غیر از این موارد باشد، سرویس‌گیرنده خطای مفید و مشخصی دریافت خواهد کرد.
* بررسی وجود پارامتر پرسمان اختیاری `q` (مانند `http://127.0.0.1:8000/items/foo?q=somequery`) در درخواست‌های `GET`.
* از آنجا که پارامتر `q` با `= None` مقداردهی شده است، این پارامتر اختیاری است.
* اگر از مقدار اولیه `None` استفاده نکنیم، این پارامتر الزامی خواهد بود (همانند بدنه درخواست در درخواست `PUT`).
* برای درخواست‌های `PUT` به آدرس `/items/{item_id}`، بدنه درخواست باید از نوع JSON تعریف شده باشد:
* بررسی اینکه بدنه شامل فیلدی با نام `name` و از نوع `str` است.
* بررسی اینکه بدنه شامل فیلدی با نام `price` و از نوع `float` است.
* بررسی اینکه بدنه شامل فیلدی اختیاری با نام `is_offer` است، که در صورت وجود باید از نوع `bool` باشد.
* تمامی این موارد برای اشیاء JSON در هر عمقی قابل بررسی می‌باشد.
* تبدیل از/به JSON به صورت خودکار.
* مستندسازی همه چیز با استفاده از OpenAPI، که می‌توان از آن برای موارد زیر استفاده کرد:
* سیستم مستندات تعاملی.
* تولید خودکار کد سرویس‌گیرنده در زبان‌های برنامه‌نویسی بیشمار.
* فراهم سازی ۲ مستند تعاملی مبتنی بر وب به صورت پیش‌فرض.
---
موارد ذکر شده تنها پاره‌ای از ویژگی‌های بیشمار FastAPI است اما ایده‌ای کلی از طرز کار آن در اختیار قرار می‌دهد.
خط زیر را به این صورت تغییر دهید:
```Python
return {"item_name": item.name, "item_id": item_id}
```
از:
```Python
... "item_name": item.name ...
```
به:
```Python
... "item_price": item.price ...
```
در حین تایپ کردن توجه کنید که چگونه ویرایشگر، ویژگی‌های کلاس `Item` را تشخیص داده و به تکمیل خودکار آنها کمک می‌کند:
برای مشاهده مثال‌های کامل‌تر که شامل قابلیت‌های بیشتری از FastAPI باشد به بخش آموزش - راهنمای کاربر مراجعه کنید.
**هشدار اسپویل**: بخش آموزش - راهنمای کاربر شامل موارد زیر است:
* اعلان **پارامترهای** موجود در بخش‌های دیگر درخواست، شامل: **سرآیند (هدر)ها**، **کوکی‌ها**، **فیلد‌های فرم** و **فایل‌ها**.
* چگونگی تنظیم **محدودیت‌های اعتبارسنجی** به عنوان مثال `maximum_length` یا `regex`.
* سیستم **Dependency Injection** قوی و کاربردی.
* امنیت و تایید هویت, شامل پشتیبانی از **OAuth2** مبتنی بر **JWT tokens** و **HTTP Basic**.
* تکنیک پیشرفته برای تعریف **مدل‌های چند سطحی JSON** (بر اساس Pydantic).
* قابلیت‌های اضافی دیگر (بر اساس Starlette) شامل:
* **وب‌سوکت**
* **GraphQL**
* تست‌های خودکار آسان مبتنی بر HTTPX و `pytest`
* **CORS**
* **Cookie Sessions**
* و موارد بیشمار دیگر.
## کارایی
معیار (بنچمارک)های مستقل TechEmpower حاکی از آن است که برنامه‌های **FastAPI** که تحت Uvicorn اجرا می‌شود، یکی از سریع‌ترین فریم‌ورک‌های مبتنی بر پایتون، است که کمی ضعیف‌تر از Starlette و Uvicorn عمل می‌کند (فریم‌ورک و سروری که FastAPI بر اساس آنها ایجاد شده است) (*)
برای درک بهتری از این موضوع به بخش بنچ‌مارک‌ها مراجعه کنید.
## نیازمندی‌های اختیاری
استفاده شده توسط Pydantic:
* email-validator - برای اعتبارسنجی آدرس‌های ایمیل.
استفاده شده توسط Starlette:
* HTTPX - در صورتی که می‌خواهید از `TestClient` استفاده کنید.
* aiofiles - در صورتی که می‌خواهید از `FileResponse` و `StaticFiles` استفاده کنید.
* jinja2 - در صورتی که بخواهید از پیکربندی پیش‌فرض برای قالب‌ها استفاده کنید.
* python-multipart - در صورتی که بخواهید با استفاده از `request.form()` از قابلیت "تجزیه (parse)" فرم استفاده کنید.
* itsdangerous - در صورتی که بخواید از `SessionMiddleware` پشتیبانی کنید.
* pyyaml - برای پشتیبانی `SchemaGenerator` در Starlet (به احتمال زیاد برای کار کردن با FastAPI به آن نیازی پیدا نمی‌کنید).
* graphene - در صورتی که از `GraphQLApp` پشتیبانی می‌کنید.
استفاده شده توسط FastAPI / Starlette:
* uvicorn - برای سرور اجرا کننده برنامه وب.
* orjson - در صورتی که بخواهید از `ORJSONResponse` استفاده کنید.
* ujson - در صورتی که بخواهید از `UJSONResponse` استفاده کنید.
می‌توان همه این موارد را با استفاده از دستور `pip install fastapi[all]`. به صورت یکجا نصب کرد.
## لایسنس
این پروژه مشمول قوانین و مقررات لایسنس MIT است.