6.9 KiB
Возврат ответа напрямую
Когда вы создаёте FastAPI операцию пути, вы можете возвращать из неё любые данные: dict, list, Pydantic-модель, модель базы данных и т.д.
Если вы объявите Модель ответа, FastAPI будет использовать её для сериализации данных в JSON с помощью Pydantic.
Если вы не объявите модель ответа, FastAPI использует jsonable_encoder, как описано в JSON кодировщик, и поместит результат в JSONResponse.
Также вы можете создать JSONResponse напрямую и вернуть его.
/// tip | Подсказка
Обычно вы получите значительно лучшую производительность, если будете использовать Модель ответа, а не возвращать JSONResponse напрямую, так как в этом случае сериализация данных с помощью Pydantic происходит на стороне Rust.
///
Возврат Response
Вы можете возвращать Response или любой его подкласс.
/// info | Информация
JSONResponse сам по себе является подклассом Response.
///
И когда вы возвращаете Response, FastAPI передаст его напрямую.
Это не приведет к преобразованию данных с помощью Pydantic-моделей, содержимое не будет преобразовано в какой-либо тип и т.д.
Это даёт вам большую гибкость. Вы можете возвращать любые типы данных, переопределять любые объявления или валидацию данных и т.д.
Это также накладывает на вас ответственность. Вам нужно удостовериться, что возвращаемые данные корректны, в правильном формате, что их можно сериализовать и т.д.
Использование jsonable_encoder в Response
Поскольку FastAPI не изменяет объект Response, который вы возвращаете, вы должны убедиться, что его содержимое готово к отправке.
Например, вы не можете поместить Pydantic-модель в JSONResponse, не преобразовав её сначала в dict с помощью преобразования всех типов данных (таких как datetime, UUID и т.д.) в совместимые с JSON типы.
В таких случаях вы можете использовать jsonable_encoder для преобразования данных перед передачей их в ответ:
{* ../../docs_src/response_directly/tutorial001_py310.py hl[5:6,20:21] *}
/// note | Технические детали
Вы также можете использовать from starlette.responses import JSONResponse.
FastAPI предоставляет starlette.responses через fastapi.responses просто для вашего удобства, как разработчика. Но большинство доступных Response-классов поступают напрямую из Starlette.
///
Возврат пользовательского Response
Пример выше показывает все необходимые части, но он пока не очень полезен, так как вы могли бы просто вернуть item напрямую, и FastAPI поместил бы его в JSONResponse, преобразовав в dict и т.д. Всё это происходит по умолчанию.
Теперь давайте посмотрим, как можно использовать это для возврата пользовательского ответа.
Допустим, вы хотите вернуть ответ в формате XML.
Вы можете поместить ваш XML-контент в строку, поместить её в Response и вернуть:
{* ../../docs_src/response_directly/tutorial002_py310.py hl[1,18] *}
Как работает модель ответа
Когда вы объявляете Модель ответа - возвращаемый тип в операции пути, FastAPI будет использовать её для сериализации данных в JSON с помощью Pydantic.
{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *}
Поскольку это происходит на стороне Rust, производительность будет значительно выше, чем если бы это выполнялось обычным Python и классом JSONResponse.
При использовании response_model или возвращаемого типа FastAPI не будет использовать jsonable_encoder для преобразования данных (что было бы медленнее) и не будет использовать класс JSONResponse.
Вместо этого он берёт JSON-байты, сгенерированные Pydantic с использованием модели ответа (или возвращаемого типа), и возвращает Response с правильным типом содержимого для JSON (application/json) напрямую.
Примечания
Когда вы возвращаете объект Response напрямую, его данные не валидируются, не преобразуются (не сериализуются) и не документируются автоматически.
Но вы всё равно можете задокументировать это, как описано в Дополнительные ответы в OpenAPI.
В следующих разделах вы увидите, как использовать/объявлять такие кастомные Response, при этом сохраняя автоматическое преобразование данных, документацию и т.д.