Motov Yurii
4 days ago
committed by
GitHub
GitHub
9 changed files with 161 additions and 9 deletions
@ -0,0 +1,41 @@ |
|||
# Дополнительные статус коды |
|||
|
|||
По умолчанию **FastAPI** возвращает ответы, используя `JSONResponse`, помещая содержимое, которое вы возвращаете из вашей *операции пути*, внутрь этого `JSONResponse`. |
|||
|
|||
Он будет использовать код статуса по умолчанию или тот, который вы укажете в вашей *операции пути*. |
|||
|
|||
## Дополнительные статус коды |
|||
|
|||
Если вы хотите возвращать дополнительный статус код помимо основного, вы можете сделать это, возвращая объект `Response` напрямую, как `JSONResponse`, и устанавливая нужный статус код напрямую. |
|||
|
|||
Например, скажем, вы хотите создать *операцию пути*, которая позволяет обновлять элементы и возвращает HTTP-код 200 "OK" при успешном выполнении. |
|||
|
|||
Но вы также хотите, чтобы она принимала новые элементы. И если элемент ранее не существовал, он создаётся, и возвращался HTTP-код 201 "Created". |
|||
|
|||
Чтобы реализовать это, импортируйте `JSONResponse` и возвращайте ваш контент напрямую, устанавливая нужный `status_code`: |
|||
|
|||
{* ../../docs_src/additional_status_codes/tutorial001_an_py310.py hl[4,25] *} |
|||
|
|||
/// warning | Внимание |
|||
|
|||
Когда вы возвращаете объект `Response` напрямую, как в примере выше, он будет возвращён как есть. |
|||
|
|||
Он не будет сериализован при помощи модели и т.д. |
|||
|
|||
Убедитесь, что в нём содержатся именно те данные, которые вы хотите, и что значения являются валидным JSON (если вы используете `JSONResponse`). |
|||
|
|||
/// |
|||
|
|||
/// note | Технические детали |
|||
|
|||
Вы также можете использовать `from starlette.responses import JSONResponse`. |
|||
|
|||
**FastAPI** предоставляет тот же `starlette.responses` через `fastapi.responses` просто для вашего удобства, как разработчика. Но большинство доступных Response-классов поступают напрямую из Starlette. То же самое касается и `status`. |
|||
|
|||
/// |
|||
|
|||
## OpenAPI и документация API |
|||
|
|||
Если вы возвращаете дополнительные коды статусов и ответы напрямую, они не будут включены в схему OpenAPI (документацию API), потому что FastAPI не может заранее знать, что вы собираетесь вернуть. |
|||
|
|||
Но вы можете задокументировать это в вашем коде, используя: [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}. |
|||
@ -0,0 +1,65 @@ |
|||
# Возврат ответа напрямую |
|||
|
|||
Когда вы создаёте **FastAPI** *операцию пути*, вы можете возвращать из неё любые данные: `dict`, `list`, Pydantic-модель, модель базы данных и т.д. |
|||
|
|||
По умолчанию **FastAPI** автоматически преобразует возвращаемое значение в JSON с помощью `jsonable_encoder`, как описано в [JSON кодировщик](../tutorial/encoder.md){.internal-link target=_blank}. |
|||
|
|||
Затем "под капотом" эти данные, совместимые с JSON (например `dict`), помещаются в `JSONResponse`, который используется для отправки ответа клиенту. |
|||
|
|||
Но вы можете возвращать `JSONResponse` напрямую из ваших *операций пути*. |
|||
|
|||
Это может быть полезно, например, если нужно вернуть пользовательские заголовки или куки. |
|||
|
|||
## Возврат `Response` |
|||
|
|||
На самом деле, вы можете возвращать любой объект `Response` или его подкласс. |
|||
|
|||
/// tip | Подсказка |
|||
|
|||
`JSONResponse` сам по себе является подклассом `Response`. |
|||
|
|||
/// |
|||
|
|||
И когда вы возвращаете `Response`, **FastAPI** передаст его напрямую. |
|||
|
|||
Это не приведет к преобразованию данных с помощью Pydantic-моделей, содержимое не будет преобразовано в какой-либо тип и т.д. |
|||
|
|||
Это даёт вам большую гибкость. Вы можете возвращать любые типы данных, переопределять любые объявления или валидацию данных и т.д. |
|||
|
|||
## Использование `jsonable_encoder` в `Response` |
|||
|
|||
Поскольку **FastAPI** не изменяет объект `Response`, который вы возвращаете, вы должны убедиться, что его содержимое готово к отправке. |
|||
|
|||
Например, вы не можете поместить Pydantic-модель в `JSONResponse`, не преобразовав её сначала в `dict` с помощью преобразования всех типов данных (таких как `datetime`, `UUID` и т.д.) в совместимые с JSON типы. |
|||
|
|||
В таких случаях вы можете использовать `jsonable_encoder` для преобразования данных перед передачей их в ответ: |
|||
|
|||
{* ../../docs_src/response_directly/tutorial001.py hl[6:7,21:22] *} |
|||
|
|||
/// note | Технические детали |
|||
|
|||
Вы также можете использовать `from starlette.responses import JSONResponse`. |
|||
|
|||
**FastAPI** предоставляет `starlette.responses` через `fastapi.responses` просто для вашего удобства, как разработчика. Но большинство доступных Response-классов поступают напрямую из Starlette. |
|||
|
|||
/// |
|||
|
|||
## Возврат пользовательского `Response` |
|||
|
|||
Пример выше показывает все необходимые части, но он пока не очень полезен, так как вы могли бы просто вернуть `item` напрямую, и **FastAPI** поместил бы его в `JSONResponse`, преобразовав в `dict` и т.д. Всё это происходит по умолчанию. |
|||
|
|||
Теперь давайте посмотрим, как можно использовать это для возврата пользовательского ответа. |
|||
|
|||
Допустим, вы хотите вернуть ответ в формате <a href="https://en.wikipedia.org/wiki/XML" class="external-link" target="_blank">XML</a>. |
|||
|
|||
Вы можете поместить ваш XML-контент в строку, поместить её в `Response` и вернуть: |
|||
|
|||
{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *} |
|||
|
|||
## Примечания |
|||
|
|||
Когда вы возвращаете объект `Response` напрямую, его данные не валидируются, не преобразуются (не сериализуются) и не документируются автоматически. |
|||
|
|||
Но вы всё равно можете задокументировать это, как описано в [Дополнительные ответы в OpenAPI](additional-responses.md){.internal-link target=_blank}. |
|||
|
|||
В следующих разделах вы увидите, как использовать/объявлять такие кастомные `Response`, при этом сохраняя автоматическое преобразование данных, документацию и т.д. |
|||
Loading…
Reference in new issue