Lorhan Sohaky
2 years ago
committed by
GitHub
GitHub
46 changed files with 839 additions and 158 deletions
|
After Width: | Height: | Size: 6.2 KiB |
|
After Width: | Height: | Size: 5.6 KiB |
@ -0,0 +1,80 @@ |
|||
# Учебник - Руководство пользователя - Введение |
|||
|
|||
В этом руководстве шаг за шагом показано, как использовать **FastApi** с большинством его функций. |
|||
|
|||
Каждый раздел постепенно основывается на предыдущих, но он структурирован по отдельным темам, так что вы можете перейти непосредственно к конкретной теме для решения ваших конкретных потребностей в API. |
|||
|
|||
Он также создан для использования в качестве будущего справочника. |
|||
|
|||
Так что вы можете вернуться и посмотреть именно то, что вам нужно. |
|||
|
|||
## Запустите код |
|||
|
|||
Все блоки кода можно копировать и использовать напрямую (на самом деле это проверенные файлы Python). |
|||
|
|||
Чтобы запустить любой из примеров, скопируйте код в файл `main.py` и запустите `uvicorn` с параметрами: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:app --reload |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
<span style="color: green;">INFO</span>: Started reloader process [28720] |
|||
<span style="color: green;">INFO</span>: Started server process [28722] |
|||
<span style="color: green;">INFO</span>: Waiting for application startup. |
|||
<span style="color: green;">INFO</span>: Application startup complete. |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
**НАСТОЯТЕЛЬНО рекомендуется**, чтобы вы написали или скопировали код, отредактировали его и запустили локально. |
|||
|
|||
Использование кода в вашем редакторе — это то, что действительно показывает вам преимущества FastAPI, видя, как мало кода вам нужно написать, все проверки типов, автодополнение и т.д. |
|||
|
|||
--- |
|||
|
|||
## Установка FastAPI |
|||
|
|||
Первый шаг — установить FastAPI. |
|||
|
|||
Для руководства вы, возможно, захотите установить его со всеми дополнительными зависимостями и функциями: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install "fastapi[all]" |
|||
|
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
...это также включает `uvicorn`, который вы можете использовать в качестве сервера, который запускает ваш код. |
|||
|
|||
!!! note "Технические детали" |
|||
Вы также можете установить его по частям. |
|||
|
|||
Это то, что вы, вероятно, сделаете, когда захотите развернуть свое приложение в рабочей среде: |
|||
|
|||
``` |
|||
pip install fastapi |
|||
``` |
|||
|
|||
Также установите `uvicorn` для работы в качестве сервера: |
|||
|
|||
``` |
|||
pip install "uvicorn[standard]" |
|||
``` |
|||
|
|||
И то же самое для каждой из необязательных зависимостей, которые вы хотите использовать. |
|||
|
|||
## Продвинутое руководство пользователя |
|||
|
|||
Существует также **Продвинутое руководство пользователя**, которое вы сможете прочитать после руководства **Учебник - Руководство пользователя**. |
|||
|
|||
**Продвинутое руководство пользователя** основано на этом, использует те же концепции и учит вас некоторым дополнительным функциям. |
|||
|
|||
Но вы должны сначала прочитать **Учебник - Руководство пользователя** (то, что вы читаете прямо сейчас). |
|||
|
|||
Он разработан таким образом, что вы можете создать полноценное приложение, используя только **Учебник - Руководство пользователя**, а затем расширить его различными способами, в зависимости от ваших потребностей, используя некоторые дополнительные идеи из **Продвинутого руководства пользователя**. |
|||
@ -0,0 +1,189 @@ |
|||
# Объявление примера запроса данных |
|||
|
|||
Вы можете объявлять примеры данных, которые ваше приложение может получать. |
|||
|
|||
Вот несколько способов, как это можно сделать. |
|||
|
|||
## Pydantic `schema_extra` |
|||
|
|||
Вы можете объявить ключ `example` для модели Pydantic, используя класс `Config` и переменную `schema_extra`, как описано в <a href="https://pydantic-docs.helpmanual.io/usage/schema/#schema-customization" class="external-link" target="_blank">Pydantic документации: Настройка схемы</a>: |
|||
|
|||
=== "Python 3.10+" |
|||
|
|||
```Python hl_lines="13-21" |
|||
{!> ../../../docs_src/schema_extra_example/tutorial001_py310.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="15-23" |
|||
{!> ../../../docs_src/schema_extra_example/tutorial001.py!} |
|||
``` |
|||
|
|||
Эта дополнительная информация будет включена в **JSON Schema** выходных данных для этой модели, и она будет использоваться в документации к API. |
|||
|
|||
!!! tip Подсказка |
|||
Вы можете использовать тот же метод для расширения JSON-схемы и добавления своей собственной дополнительной информации. |
|||
|
|||
Например, вы можете использовать это для добавления дополнительной информации для пользовательского интерфейса в вашем веб-приложении и т.д. |
|||
|
|||
## Дополнительные аргументы поля `Field` |
|||
|
|||
При использовании `Field()` с моделями Pydantic, вы также можете объявлять дополнительную информацию для **JSON Schema**, передавая любые другие произвольные аргументы в функцию. |
|||
|
|||
Вы можете использовать это, чтобы добавить аргумент `example` для каждого поля: |
|||
|
|||
=== "Python 3.10+" |
|||
|
|||
```Python hl_lines="2 8-11" |
|||
{!> ../../../docs_src/schema_extra_example/tutorial002_py310.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="4 10-13" |
|||
{!> ../../../docs_src/schema_extra_example/tutorial002.py!} |
|||
``` |
|||
|
|||
!!! warning Внимание |
|||
Имейте в виду, что эти дополнительные переданные аргументы не добавляют никакой валидации, только дополнительную информацию для документации. |
|||
|
|||
## Использование `example` и `examples` в OpenAPI |
|||
|
|||
При использовании любой из этих функций: |
|||
|
|||
* `Path()` |
|||
* `Query()` |
|||
* `Header()` |
|||
* `Cookie()` |
|||
* `Body()` |
|||
* `Form()` |
|||
* `File()` |
|||
|
|||
вы также можете добавить аргумент, содержащий `example` или группу `examples` с дополнительной информацией, которая будет добавлена в **OpenAPI**. |
|||
|
|||
### Параметр `Body` с аргументом `example` |
|||
|
|||
Здесь мы передаём аргумент `example`, как пример данных ожидаемых в параметре `Body()`: |
|||
|
|||
=== "Python 3.10+" |
|||
|
|||
```Python hl_lines="22-27" |
|||
{!> ../../../docs_src/schema_extra_example/tutorial003_an_py310.py!} |
|||
``` |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="22-27" |
|||
{!> ../../../docs_src/schema_extra_example/tutorial003_an_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="23-28" |
|||
{!> ../../../docs_src/schema_extra_example/tutorial003_an.py!} |
|||
``` |
|||
|
|||
=== "Python 3.10+ non-Annotated" |
|||
|
|||
!!! tip Заметка |
|||
Рекомендуется использовать версию с `Annotated`, если это возможно. |
|||
|
|||
```Python hl_lines="18-23" |
|||
{!> ../../../docs_src/schema_extra_example/tutorial003_py310.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+ non-Annotated" |
|||
|
|||
!!! tip Заметка |
|||
Рекомендуется использовать версию с `Annotated`, если это возможно. |
|||
|
|||
```Python hl_lines="20-25" |
|||
{!> ../../../docs_src/schema_extra_example/tutorial003.py!} |
|||
``` |
|||
|
|||
### Аргумент "example" в UI документации |
|||
|
|||
С любым из вышеуказанных методов это будет выглядеть так в `/docs`: |
|||
|
|||
<img src="/img/tutorial/body-fields/image01.png"> |
|||
|
|||
### `Body` с аргументом `examples` |
|||
|
|||
В качестве альтернативы одному аргументу `example`, вы можете передавать `examples` используя тип данных `dict` с **несколькими примерами**, каждый из которых содержит дополнительную информацию, которая также будет добавлена в **OpenAPI**. |
|||
|
|||
Ключи `dict` указывают на каждый пример, а значения для каждого из них - на еще один тип `dict` с дополнительной информацией. |
|||
|
|||
Каждый конкретный пример типа `dict` в аргументе `examples` может содержать: |
|||
|
|||
* `summary`: Краткое описание для примера. |
|||
* `description`: Полное описание, которое может содержать текст в формате Markdown. |
|||
* `value`: Это конкретный пример, который отображается, например, в виде типа `dict`. |
|||
* `externalValue`: альтернатива параметру `value`, URL-адрес, указывающий на пример. Хотя это может не поддерживаться таким же количеством инструментов разработки и тестирования API, как параметр `value`. |
|||
|
|||
=== "Python 3.10+" |
|||
|
|||
```Python hl_lines="23-49" |
|||
{!> ../../../docs_src/schema_extra_example/tutorial004_an_py310.py!} |
|||
``` |
|||
|
|||
=== "Python 3.9+" |
|||
|
|||
```Python hl_lines="23-49" |
|||
{!> ../../../docs_src/schema_extra_example/tutorial004_an_py39.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+" |
|||
|
|||
```Python hl_lines="24-50" |
|||
{!> ../../../docs_src/schema_extra_example/tutorial004_an.py!} |
|||
``` |
|||
|
|||
=== "Python 3.10+ non-Annotated" |
|||
|
|||
!!! tip Заметка |
|||
Рекомендуется использовать версию с `Annotated`, если это возможно. |
|||
|
|||
```Python hl_lines="19-45" |
|||
{!> ../../../docs_src/schema_extra_example/tutorial004_py310.py!} |
|||
``` |
|||
|
|||
=== "Python 3.6+ non-Annotated" |
|||
|
|||
!!! tip Заметка |
|||
Рекомендуется использовать версию с `Annotated`, если это возможно. |
|||
|
|||
```Python hl_lines="21-47" |
|||
{!> ../../../docs_src/schema_extra_example/tutorial004.py!} |
|||
``` |
|||
|
|||
### Аргумент "examples" в UI документации |
|||
|
|||
С аргументом `examples`, добавленным в `Body()`, страница документации `/docs` будет выглядеть так: |
|||
|
|||
<img src="/img/tutorial/body-fields/image02.png"> |
|||
|
|||
## Технические Детали |
|||
|
|||
!!! warning Внимание |
|||
Эти технические детали относятся к стандартам **JSON Schema** и **OpenAPI**. |
|||
|
|||
Если предложенные выше идеи уже работают для вас, возможно этого будет достаточно и эти детали вам не потребуются, можете спокойно их пропустить. |
|||
|
|||
Когда вы добавляете пример внутрь модели Pydantic, используя `schema_extra` или `Field(example="something")`, этот пример добавляется в **JSON Schema** для данной модели Pydantic. |
|||
|
|||
И эта **JSON Schema** модели Pydantic включается в **OpenAPI** вашего API, а затем используется в UI документации. |
|||
|
|||
Поля `example` как такового не существует в стандартах **JSON Schema**. В последних версиях JSON-схемы определено поле <a href="https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.9.5" class="external-link" target="_blank">`examples`</a>, но OpenAPI 3.0.3 основан на более старой версии JSON-схемы, которая не имела поля `examples`. |
|||
|
|||
Таким образом, OpenAPI 3.0.3 определяет своё собственное поле <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#fixed-fields-20" class="external-link" target="_blank">`example`</a> для модифицированной версии **JSON Schema**, которую он использует чтобы достичь той же цели (однако это именно поле `example`, а не `examples`), и именно это используется API в UI документации (с интеграцией Swagger UI). |
|||
|
|||
Итак, хотя поле `example` не является частью JSON-схемы, оно является частью настраиваемой версии JSON-схемы в OpenAPI, и именно это поле будет использоваться в UI документации. |
|||
|
|||
Однако, когда вы используете поле `example` или `examples` с любой другой функцией (`Query()`, `Body()`, и т.д.), эти примеры не добавляются в JSON-схему, которая описывает эти данные (даже в собственную версию JSON-схемы OpenAPI), они добавляются непосредственно в объявление *операции пути* в OpenAPI (вне частей OpenAPI, которые используют JSON-схему). |
|||
|
|||
Для функций `Path()`, `Query()`, `Header()`, и `Cookie()`, аргументы `example` или `examples` добавляются в <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameter-object" class="external-link" target="_blank">определение OpenAPI, к объекту `Parameter Object` (в спецификации)</a>. |
|||
|
|||
И для функций `Body()`, `File()` и `Form()` аргументы `example` или `examples` аналогично добавляются в <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#mediaTypeObject" class="external-link" target="_blank"> определение OpenAPI, к объекту `Request Body Object`, в поле `content` в объекте `Media Type Object` (в спецификации)</a>. |
|||
|
|||
С другой стороны, существует более новая версия OpenAPI: **3.1.0**, недавно выпущенная. Она основана на последней версии JSON-схемы и большинство модификаций из OpenAPI JSON-схемы удалены в обмен на новые возможности из последней версии JSON-схемы, так что все эти мелкие отличия устранены. Тем не менее, Swagger UI в настоящее время не поддерживает OpenAPI 3.1.0, поэтому пока лучше продолжать использовать вышеупомянутые методы. |
|||
@ -0,0 +1,31 @@ |
|||
# 响应 - 更改状态码 |
|||
|
|||
你可能之前已经了解到，你可以设置默认的[响应状态码](../tutorial/response-status-code.md){.internal-link target=_blank}。 |
|||
|
|||
但在某些情况下，你需要返回一个不同于默认值的状态码。 |
|||
|
|||
## 使用场景 |
|||
|
|||
例如，假设你想默认返回一个HTTP状态码为“OK”`200`。 |
|||
|
|||
但如果数据不存在，你想创建它，并返回一个HTTP状态码为“CREATED”`201`。 |
|||
|
|||
但你仍然希望能够使用`response_model`过滤和转换你返回的数据。 |
|||
|
|||
对于这些情况，你可以使用一个`Response`参数。 |
|||
|
|||
## 使用 `Response` 参数 |
|||
|
|||
你可以在你的*路径操作函数*中声明一个`Response`类型的参数（就像你可以为cookies和头部做的那样）。 |
|||
|
|||
然后你可以在这个*临时*响应对象中设置`status_code`。 |
|||
|
|||
```Python hl_lines="1 9 12" |
|||
{!../../../docs_src/response_change_status_code/tutorial001.py!} |
|||
``` |
|||
|
|||
然后你可以像平常一样返回任何你需要的对象（例如一个`dict`或者一个数据库模型）。如果你声明了一个`response_model`，它仍然会被用来过滤和转换你返回的对象。 |
|||
|
|||
**FastAPI**将使用这个临时响应来提取状态码（也包括cookies和头部），并将它们放入包含你返回的值的最终响应中，该响应由任何`response_model`过滤。 |
|||
|
|||
你也可以在依赖项中声明`Response`参数，并在其中设置状态码。但请注意，最后设置的状态码将会生效。 |
|||
@ -0,0 +1,39 @@ |
|||
# 响应头 |
|||
|
|||
## 使用 `Response` 参数 |
|||
|
|||
你可以在你的*路径操作函数*中声明一个`Response`类型的参数（就像你可以为cookies做的那样）。 |
|||
|
|||
然后你可以在这个*临时*响应对象中设置头部。 |
|||
```Python hl_lines="1 7-8" |
|||
{!../../../docs_src/response_headers/tutorial002.py!} |
|||
``` |
|||
|
|||
然后你可以像平常一样返回任何你需要的对象（例如一个`dict`或者一个数据库模型）。如果你声明了一个`response_model`，它仍然会被用来过滤和转换你返回的对象。 |
|||
|
|||
**FastAPI**将使用这个临时响应来提取头部（也包括cookies和状态码），并将它们放入包含你返回的值的最终响应中，该响应由任何`response_model`过滤。 |
|||
|
|||
你也可以在依赖项中声明`Response`参数，并在其中设置头部（和cookies）。 |
|||
|
|||
## 直接返回 `Response` |
|||
|
|||
你也可以在直接返回`Response`时添加头部。 |
|||
|
|||
按照[直接返回响应](response-directly.md){.internal-link target=_blank}中所述创建响应，并将头部作为附加参数传递： |
|||
```Python hl_lines="10-12" |
|||
{!../../../docs_src/response_headers/tutorial001.py!} |
|||
``` |
|||
|
|||
|
|||
!!! 注意 "技术细节" |
|||
你也可以使用`from starlette.responses import Response`或`from starlette.responses import JSONResponse`。 |
|||
|
|||
**FastAPI**提供了与`fastapi.responses`相同的`starlette.responses`，只是为了方便开发者。但是，大多数可用的响应都直接来自Starlette。 |
|||
|
|||
由于`Response`经常用于设置头部和cookies，因此**FastAPI**还在`fastapi.Response`中提供了它。 |
|||
|
|||
## 自定义头部 |
|||
|
|||
请注意，可以使用'X-'前缀添加自定义专有头部。 |
|||
|
|||
但是，如果你有自定义头部，你希望浏览器中的客户端能够看到它们，你需要将它们添加到你的CORS配置中（在[CORS（跨源资源共享）](../tutorial/cors.md){.internal-link target=_blank}中阅读更多），使用在<a href="https://www.starlette.io/middleware/#corsmiddleware" class="external-link" target="_blank">Starlette的CORS文档</a>中记录的`expose_headers`参数。 |
|||
@ -0,0 +1,8 @@ |
|||
-e . |
|||
mkdocs >=1.1.2,<2.0.0 |
|||
mkdocs-material >=8.1.4,<9.0.0 |
|||
mdx-include >=1.4.1,<2.0.0 |
|||
mkdocs-markdownextradata-plugin >=0.1.7,<0.3.0 |
|||
typer-cli >=0.0.13,<0.0.14 |
|||
typer[all] >=0.6.1,<0.8.0 |
|||
pyyaml >=5.3.1,<7.0.0 |
|||
@ -0,0 +1,25 @@ |
|||
-e . |
|||
pytest >=7.1.3,<8.0.0 |
|||
coverage[toml] >= 6.5.0,< 8.0 |
|||
mypy ==1.3.0 |
|||
ruff ==0.0.272 |
|||
black == 23.3.0 |
|||
httpx >=0.23.0,<0.24.0 |
|||
email_validator >=1.1.1,<2.0.0 |
|||
# TODO: once removing databases from tutorial, upgrade SQLAlchemy |
|||
# probably when including SQLModel |
|||
sqlalchemy >=1.3.18,<1.4.43 |
|||
peewee >=3.13.3,<4.0.0 |
|||
databases[sqlite] >=0.3.2,<0.7.0 |
|||
orjson >=3.2.1,<4.0.0 |
|||
ujson >=4.0.1,!=4.0.2,!=4.1.0,!=4.2.0,!=4.3.0,!=5.0.0,!=5.1.0,<6.0.0 |
|||
python-multipart >=0.0.5,<0.0.7 |
|||
flask >=1.1.2,<3.0.0 |
|||
anyio[trio] >=3.2.1,<4.0.0 |
|||
python-jose[cryptography] >=3.3.0,<4.0.0 |
|||
pyyaml >=5.3.1,<7.0.0 |
|||
passlib[bcrypt] >=1.7.2,<2.0.0 |
|||
|
|||
# types |
|||
types-ujson ==5.7.0.1 |
|||
types-orjson ==3.6.2 |
|||
@ -0,0 +1,5 @@ |
|||
-e .[all] |
|||
-r requirements-tests.txt |
|||
-r requirements-docs.txt |
|||
uvicorn[standard] >=0.12.0,<0.21.0 |
|||
pre-commit >=2.17.0,<3.0.0 |
|||
@ -0,0 +1,73 @@ |
|||
import json |
|||
from typing import List |
|||
|
|||
from fastapi import APIRouter, Depends, FastAPI, WebSocket |
|||
from fastapi.testclient import TestClient |
|||
from typing_extensions import Annotated |
|||
|
|||
|
|||
def dependency_list() -> List[str]: |
|||
return [] |
|||
|
|||
|
|||
DepList = Annotated[List[str], Depends(dependency_list)] |
|||
|
|||
|
|||
def create_dependency(name: str): |
|||
def fun(deps: DepList): |
|||
deps.append(name) |
|||
|
|||
return Depends(fun) |
|||
|
|||
|
|||
router = APIRouter(dependencies=[create_dependency("router")]) |
|||
prefix_router = APIRouter(dependencies=[create_dependency("prefix_router")]) |
|||
app = FastAPI(dependencies=[create_dependency("app")]) |
|||
|
|||
|
|||
@app.websocket("/", dependencies=[create_dependency("index")]) |
|||
async def index(websocket: WebSocket, deps: DepList): |
|||
await websocket.accept() |
|||
await websocket.send_text(json.dumps(deps)) |
|||
await websocket.close() |
|||
|
|||
|
|||
@router.websocket("/router", dependencies=[create_dependency("routerindex")]) |
|||
async def routerindex(websocket: WebSocket, deps: DepList): |
|||
await websocket.accept() |
|||
await websocket.send_text(json.dumps(deps)) |
|||
await websocket.close() |
|||
|
|||
|
|||
@prefix_router.websocket("/", dependencies=[create_dependency("routerprefixindex")]) |
|||
async def routerprefixindex(websocket: WebSocket, deps: DepList): |
|||
await websocket.accept() |
|||
await websocket.send_text(json.dumps(deps)) |
|||
await websocket.close() |
|||
|
|||
|
|||
app.include_router(router, dependencies=[create_dependency("router2")]) |
|||
app.include_router( |
|||
prefix_router, prefix="/prefix", dependencies=[create_dependency("prefix_router2")] |
|||
) |
|||
|
|||
|
|||
def test_index(): |
|||
client = TestClient(app) |
|||
with client.websocket_connect("/") as websocket: |
|||
data = json.loads(websocket.receive_text()) |
|||
assert data == ["app", "index"] |
|||
|
|||
|
|||
def test_routerindex(): |
|||
client = TestClient(app) |
|||
with client.websocket_connect("/router") as websocket: |
|||
data = json.loads(websocket.receive_text()) |
|||
assert data == ["app", "router2", "router", "routerindex"] |
|||
|
|||
|
|||
def test_routerprefixindex(): |
|||
client = TestClient(app) |
|||
with client.websocket_connect("/prefix/") as websocket: |
|||
data = json.loads(websocket.receive_text()) |
|||
assert data == ["app", "prefix_router2", "prefix_router", "routerprefixindex"] |
|||
Loading…
Reference in new issue