mirror of https://github.com/tiangolo/fastapi.git
🌐 Add Persian translation for `docs/fa/docs/features.md` (#5887)
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Sebastián Ramírez <tiangolo@gmail.com> Co-authored-by: Amin Alaee <mohammadamin.alaee@gmail.com>
This commit is contained in:
Amir Khorasani
GitHub
parent
60e1259ca4
commit
7d8241acb9
|
|
@ -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