Browse Source
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Sebastián Ramírez <[email protected]> Co-authored-by: Amin Alaee <[email protected]>pull/10922/head
Amir Khorasani
1 year ago
committed by
GitHub
GitHub
1 changed files with 206 additions and 0 deletions
@ -0,0 +1,206 @@ |
|||||
|
# ویژگی ها |
||||
|
|
||||
|
## ویژگی های FastAPI |
||||
|
|
||||
|
**FastAPI** موارد زیر را به شما ارائه میدهد: |
||||
|
|
||||
|
### برپایه استاندارد های باز |
||||
|
|
||||
|
* <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank"><strong>OpenAPI</strong></a> برای ساخت API, شامل مشخص سازی <abbr title="که علاوه بر path, به عنوان endpoint و route نیز شناخته میشود">path</abbr> <abbr title="که به عنوان متودهای HTTP یعنی POST,GET,PUT,DELETE و ... شناخته میشوند">operation</abbr> ها, <abbr title="parameters">پارامترها</abbr>, body request ها, امنیت و غیره. |
||||
|
* مستندسازی خودکار data model با <a href="https://json-schema.org/" class="external-link" target="_blank"><strong>JSON Schema</strong></a> (همانطور که OpenAPI خود نیز مبتنی بر JSON Schema است). |
||||
|
* طراحی شده بر اساس استاندارد هایی که پس از یک مطالعه دقیق بدست آمده اند بجای طرحی ناپخته و بدون فکر. |
||||
|
* همچنین به شما اجازه میدهد تا از تولید خودکار client code در بسیاری از زبان ها استفاده کنید. |
||||
|
|
||||
|
### مستندات خودکار |
||||
|
|
||||
|
مستندات API تعاملی و ایجاد رابط کاربری وب. از آنجایی که این فریم ورک برپایه OpenAPI میباشد، آپشن های متعددی وجود دارد که ۲ مورد بصورت پیش فرض گنجانده شده اند. |
||||
|
|
||||
|
* <a href="https://github.com/swagger-api/swagger-ui" class="external-link" target="_blank"><strong>Swagger UI</strong></a>، با <abbr title="interactive exploration">کاوش تعاملی</abbr>، API خود را مستقیما از طریق مرورگر صدازده و تست کنید. |
||||
|
|
||||
|
 |
||||
|
|
||||
|
* مستندات API جایگزین با <a href="https://github.com/Rebilly/ReDoc" class="external-link" target="_blank"><strong>ReDoc</strong></a>. |
||||
|
|
||||
|
 |
||||
|
|
||||
|
### فقط پایتون مدرن |
||||
|
|
||||
|
همه اینها برپایه type declaration های **پایتون ۳.۶** استاندارد (به لطف Pydantic) میباشند. سینتکس جدیدی درکار نیست. تنها پایتون مدرن استاندارد. |
||||
|
|
||||
|
اگر به یک یادآوری ۲ دقیقه ای در مورد نحوه استفاده از تایپ های پایتون دارید (حتی اگر از FastAPI استفاده نمیکنید) این آموزش کوتاه را بررسی کنید: [Python Types](python-types.md){.internal-link target=\_blank}. |
||||
|
|
||||
|
شما پایتون استاندارد را با استفاده از تایپ ها مینویسید: |
||||
|
|
||||
|
```Python |
||||
|
from datetime import date |
||||
|
|
||||
|
from pydantic import BaseModel |
||||
|
|
||||
|
# Declare a variable as a str |
||||
|
# and get editor support inside the function |
||||
|
def main(user_id: str): |
||||
|
return user_id |
||||
|
|
||||
|
|
||||
|
# A Pydantic model |
||||
|
class User(BaseModel): |
||||
|
id: int |
||||
|
name: str |
||||
|
joined: date |
||||
|
``` |
||||
|
|
||||
|
که سپس میتوان به این شکل از آن استفاده کرد: |
||||
|
|
||||
|
```Python |
||||
|
my_user: User = User(id=3, name="John Doe", joined="2018-07-19") |
||||
|
|
||||
|
second_user_data = { |
||||
|
"id": 4, |
||||
|
"name": "Mary", |
||||
|
"joined": "2018-11-30", |
||||
|
} |
||||
|
|
||||
|
my_second_user: User = User(**second_user_data) |
||||
|
``` |
||||
|
|
||||
|
!!! info |
||||
|
`**second_user_data` یعنی: |
||||
|
|
||||
|
کلید ها و مقادیر دیکشنری `second_user_data` را مستقیما به عنوان ارگومان های key-value بفرست، که معادل است با : `User(id=4, name="Mary", joined="2018-11-30")` |
||||
|
|
||||
|
### پشتیبانی ویرایشگر |
||||
|
|
||||
|
تمام فریم ورک به گونه ای طراحی شده که استفاده از آن آسان و شهودی باشد، تمام تصمیمات حتی قبل از شروع توسعه بر روی چندین ویرایشگر آزمایش شده اند، تا از بهترین تجربه توسعه اطمینان حاصل شود. |
||||
|
|
||||
|
در آخرین نظرسنجی توسعه دهندگان پایتون کاملا مشخص بود که <a href="https://www.jetbrains.com/research/python-developers-survey-2017/#tools-and-features" class="external-link" target="_blank">بیشترین ویژگی مورد استفاده از "<abbr title="autocompletion">تکمیل خودکار</abbr>" است</a>. |
||||
|
|
||||
|
تمام فریم ورک **FastAPI** برپایه ای برای براورده کردن این نیاز نیز ایجاد گشته است. تکمیل خودکار در همه جا کار میکند. |
||||
|
|
||||
|
شما به ندرت نیاز به بازگشت به مستندات را خواهید داشت. |
||||
|
|
||||
|
ببینید که چگونه ویرایشگر شما ممکن است به شما کمک کند: |
||||
|
|
||||
|
* در <a href="https://code.visualstudio.com/" class="external-link" target="_blank">Visual Studio Code</a>: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
* در <a href="https://www.jetbrains.com/pycharm/" class="external-link" target="_blank">PyCharm</a>: |
||||
|
|
||||
|
 |
||||
|
|
||||
|
شما پیشنهاد های تکمیل خودکاری را خواهید گرفت که حتی ممکن است قبلا آن را غیرممکن تصور میکردید. به عنوان مثال کلید `price` در داخل بدنه JSON (که میتوانست تودرتو نیز باشد) که از یک درخواست آمده است. |
||||
|
|
||||
|
دیگر خبری از تایپ کلید اشتباهی، برگشتن به مستندات یا پایین بالا رفتن برای فهمیدن اینکه شما از `username` یا `user_name` استفاده کرده اید نیست. |
||||
|
|
||||
|
### مختصر |
||||
|
|
||||
|
FastAPI **پیش فرض** های معقولی برای همه چیز دارد، با قابلیت تنظیمات اختیاری در همه جا. تمام پارامترها را میتوانید برای انجام انچه نیاز دارید و برای تعریف API مورد نیاز خود به خوبی تنظیم کنید. |
||||
|
|
||||
|
اما به طور پیش فرض، همه چیز **کار میکند**. |
||||
|
|
||||
|
### اعتبارسنجی |
||||
|
|
||||
|
* اعتبارسنجی برای بیشتر (یا همه؟) **data type** های پایتون، شامل: |
||||
|
|
||||
|
* JSON objects (`dict`) |
||||
|
* آرایه های (`list`) JSON با قابلیت مشخص سازی تایپ ایتم های درون لیست. |
||||
|
* فیلد های رشته (`str`)، به همراه مشخص سازی حداقل و حداکثر طول رشته. |
||||
|
* اعداد (`int`,`float`) با حداقل و حداکثر مقدار و غیره. |
||||
|
|
||||
|
* اعتبارسنجی برای تایپ های عجیب تر، مثل: |
||||
|
* URL. |
||||
|
* Email. |
||||
|
* UUID. |
||||
|
* و غیره. |
||||
|
|
||||
|
تمام اعتبارسنجی ها توسط کتابخانه اثبات شده و قدرتمند **Pydantic** انجام میشود. |
||||
|
|
||||
|
### <abbr title="Security and authentication">امنیت و احراز هویت</abbr> |
||||
|
|
||||
|
امنیت و احرازهویت بدون هیچگونه ارتباط و مصالحه ای با پایگاه های داده یا مدل های داده ایجاد شده اند. |
||||
|
|
||||
|
تمام طرح های امنیتی در OpenAPI تعریف شده اند، از جمله: |
||||
|
|
||||
|
* . |
||||
|
* **OAuth2** (همچنین با **JWT tokens**). آموزش را در [OAuth2 with JWT](tutorial/security/oauth2-jwt.md){.internal-link target=\_blank} مشاهده کنید. |
||||
|
* کلید های API: |
||||
|
* <abbr title="سرصفحه ها">Headers</abbr> |
||||
|
* <abbr title="پارامترهای پرسمان">Query parameters</abbr> |
||||
|
* <abbr title="کوکی ها">Cookies</abbr>، و غیره. |
||||
|
|
||||
|
به علاوه تمام ویژگی های امنیتی از **Statlette** (شامل **<abbr title="کوکی های جلسه">session cookies</abbr>**) |
||||
|
|
||||
|
همه اینها به عنوان ابزارها و اجزای قابل استفاده ای ساخته شده اند که به راحتی با سیستم های شما، مخازن داده، پایگاه های داده رابطه ای و NoSQL و غیره ادغام میشوند. |
||||
|
|
||||
|
### <abbr title="تزریق وابستگی">Dependency Injection</abbr> |
||||
|
|
||||
|
FastAPI شامل یک سیستم <abbr title='همچنین به عنوان "components", "resources", "services" و "providers" شناخته میشود'><strong>Dependency Injection</strong></abbr> بسیار آسان اما بسیار قدرتمند است. |
||||
|
|
||||
|
* حتی وابستگی ها نیز میتوانند وابستگی هایی داشته باشند و یک سلسله مراتب یا **"گرافی" از وابستگی ها** ایجاد کنند. |
||||
|
|
||||
|
* همه چیز توسط فریم ورک **به طور خودکار اداره میشود** |
||||
|
|
||||
|
* همه وابستگی ها میتوانند به داده های request ها نیاز داشته باشند و مستندات خودکار و محدودیت های <abbr title="عملیات مسیر">path operation</abbr> را **افزایش** دهند. |
||||
|
|
||||
|
* با قابلیت **اعتبارسنجی خودکار** حتی برای path operation parameter های تعریف شده در وابستگی ها. |
||||
|
|
||||
|
* پشتیبانی از سیستم های پیچیده احرازهویت کاربر، **اتصالات پایگاه داده** و غیره. |
||||
|
|
||||
|
* بدون هیچ ارتباطی با دیتابیس ها، فرانت اند و غیره. اما ادغام آسان و راحت با همه آنها. |
||||
|
|
||||
|
### پلاگین های نامحدود |
||||
|
|
||||
|
یا به عبارت دیگر، هیچ نیازی به آنها نیست، کد موردنیاز خود را وارد و استفاده کنید. |
||||
|
|
||||
|
هر یکپارچه سازی به گونه ای طراحی شده است که استفاده از آن بسیار ساده باشد (با وابستگی ها) که میتوانید با استفاده از همان ساختار و روشی که برای _path operation_ های خود استفاده کرده اید تنها در ۲ خط کد "پلاگین" برنامه خودتان را ایجاد کنید. |
||||
|
|
||||
|
### تست شده |
||||
|
|
||||
|
* 100% <abbr title="مقدار کدی که به طور خودکار تست شده است">پوشش تست</abbr>. |
||||
|
|
||||
|
* 100% کد بر اساس <abbr title="حاشیه نویسی تایپ های پایتون (Python type annotations)، با استفاده از آن ویرایشگر و ابزارهای خارجی شما می توانند پشتیبانی بهتری از شما ارائه دهند">type annotate ها</abbr>. |
||||
|
|
||||
|
* استفاده شده در اپلیکیشن های تولید |
||||
|
|
||||
|
## ویژگی های Starlette |
||||
|
|
||||
|
**FastAPI** کاملا (و براساس) با <a href="https://www.starlette.io/" class="external-link" target="_blank"><strong>Starlette</strong></a> سازگار است. بنابراین، هرکد اضافی Starlette که دارید، نیز کار خواهد کرد. |
||||
|
|
||||
|
`FastAPI` در واقع یک زیرکلاس از `Starlette` است. بنابراین اگر از قبل Starlette را میشناسید یا با آن کار کرده اید، بیشتر قابلیت ها به همین روش کار خواهد کرد. |
||||
|
|
||||
|
با **FastAPI** شما تمام ویژگی های **Starlette** را خواهید داشت (زیرا FastAPI یک نسخه و نمونه به تمام معنا از Starlette است): |
||||
|
|
||||
|
* عملکرد به طورجدی چشمگیر. <a href="https://github.com/encode/starlette#performance" class="external-link" target="_blank">این یکی از سریعترین فریم ورک های موجود در پایتون است که همتراز با **نود جی اس** و **گو**</a> است. |
||||
|
* پشتیبانی از **WebSocket**. |
||||
|
* <abbr title="In-process background tasks">تسک های درجریان در پس زمینه</abbr>. |
||||
|
* <abbr title="Startup and shutdown events">رویداد های راه اندازی و متوفق شدن<abbr>. |
||||
|
* تست کلاینت ساخته شده به روی HTTPX. |
||||
|
* **CORS**, GZip, فایل های استاتیک, <abbr title="Streaming responses">پاسخ های جریانی</abbr>. |
||||
|
* پشتیبانی از **نشست ها و کوکی ها**. |
||||
|
* 100% پوشش با تست. |
||||
|
* 100% کد براساس type annotate ها. |
||||
|
|
||||
|
## ویژگی های Pydantic |
||||
|
|
||||
|
**FastAPI** کاملا (و براساس) با <a href="https://pydantic-docs.helpmanual.io" class="external-link" target="_blank"><strong>Pydantic</strong></a> سازگار است. بنابراین هرکد Pydantic اضافی که داشته باشید، نیز کار خواهد کرد. |
||||
|
|
||||
|
از جمله کتابخانه های خارجی نیز مبتنی بر Pydantic میتوان به <abbr title="Object-Relational Mapper">ORM</abbr> و <abbr title="Object-Document Mapper">ODM</abbr> ها برای دیتابیس ها اشاره کرد. |
||||
|
|
||||
|
این همچنین به این معناست که در خیلی از موارد میتوانید همان ابجکتی که از request میگیرید را **مستقیما به دیتابیس** بفرستید زیرا همه چیز به طور خودکار تأیید میشود. |
||||
|
|
||||
|
همین امر برعکس نیز صدق میکند، در بسیاری از موارد شما میتوانید ابجکتی را که از پایگاه داده دریافت میکنید را **مستقیماً به کاربر** ارسال کنید. |
||||
|
|
||||
|
با FastAPI شما تمام ویژگی های Pydantic را دراختیار دارید (زیرا FastAPI برای تمام بخش مدیریت دیتا بر اساس Pydantic عمل میکند): |
||||
|
|
||||
|
* **خبری از گیج شدن نیست**: |
||||
|
* هیچ <abbr title="micro-language">زبان خردی</abbr> برای یادگیری تعریف طرحواره های جدید وجود ندارد. |
||||
|
* اگر تایپ های پایتون را میشناسید، نحوه استفاده از Pydantic را نیز میدانید. |
||||
|
* به خوبی با **<abbr title="همان Integrated Development Environment, شبیه به ویرایشگر کد">IDE</abbr>/<abbr title="برنامه ای که خطاهای کد را بررسی می کند">linter</abbr>/مغز** شما عمل میکند: |
||||
|
* به این دلیل که ساختار داده Pydantic فقط نمونه هایی از کلاس هایی هستند که شما تعریف میکنید، تکمیل خودکار، mypy، linting و مشاهده شما باید به درستی با داده های معتبر شما کار کنند. |
||||
|
* اعتبار سنجی **ساختارهای پیچیده**: |
||||
|
* استفاده از مدل های سلسله مراتبی Pydantic, `List` و `Dict` کتابخانه `typing` پایتون و غیره. |
||||
|
* و اعتبارسنج ها اجازه میدهند که طرحواره های داده پیچیده به طور واضح و آسان تعریف، بررسی و بر پایه JSON مستند شوند. |
||||
|
* شما میتوانید ابجکت های عمیقا تودرتو JSON را که همگی تایید شده و annotated شده اند را داشته باشید. |
||||
|
* **قابل توسعه**: |
||||
|
* Pydantic اجازه میدهد تا data type های سفارشی تعریف شوند یا میتوانید اعتبارسنجی را با روش هایی به روی مدل ها با <abbr title="دکوریتور های اعتبارسنج">validator decorator</abbr> گسترش دهید. |
||||
|
* 100% پوشش با تست. |
||||
Loading…
Reference in new issue