Тело запроса FastAPI
Тело запроса — это данные, отправляемые клиентом в API. Когда нужно получить JSON-данные от клиента, используйте тело запроса для их передачи. FastAPI использует модели Pydantic для объявления структуры тела запроса, автоматически выполняя проверку данных, преобразование и генерацию документации.
Разница между телом запроса и параметрами запроса
| Методы передачи данных | Position | Применимые сценарии | Методы HTTP |
|---|---|---|---|
| Параметр пути | Путь URL/items/5 | Идентифицировать ресурс | GET, PUT, DELETE и т. д. |
| Параметр запроса | В URL?key=value | Необязательные параметры, такие как фильтрация и пагинация | В основном GET |
| тело запроса | JSON-данные запроса | Отправка сложных данных | POST、PUT、PATCH |
Для отправки данных следует использовать
POST(наиболее распространённый),PUT、DELETEилиPATCHХотя FastAPI технически поддерживает GET-запросы с телом запроса, это не соответствует спецификациям HTTP, и Swagger UI не будет показывать документацию по телу запроса для GET-запросов.
Объявление тела запроса с помощью модели Pydantic
Импортируйте BaseModel
from pydantic import BaseModel
2. Создайте модель данных
Определите класс, наследующийBaseModelДля класса объявите все атрибуты, используя стандартные типы Python:
Пример
from pydantic import BaseModel
app = FastAPI()
# Определите модель данных тела запроса
class Item(BaseModel):
name: str # Обязательно: название продукта
description: str | None = None # Необязательно: описание продукта
price: float # Обязательно: цена продукта
tax: float | None = None # Необязательно: налог
@app.post("/items/")
async def create_item(item: Item):
return item
Правила того, являются ли атрибуты обязательными, такие же, как для параметров запроса:
- Атрибуты со значениями по умолчанию необязательны (например,
description、tax) - Атрибуты без значений по умолчанию обязательны (например,
name、price)
Все следующие JSON являются допустимыми телами запроса:
// 包含所有字段
{
"name": "Foo",
"description": "可选描述",
"price": 45.2,
"tax": 3.5
}
// 省略可选字段
{
"name": "Foo",
"price": 45.2
}
Обработка тела запроса в FastAPI
Просто объявив типы Python, FastAPI может автоматически выполнять следующее:
| Особенности | Описание |
|---|---|
| Чтение тела запроса | Прочитать данные из запроса в формате JSON |
| Преобразование типов | Преобразовать данные в объявленные типы (например, string в float) |
| Проверка данных | Проверять данные и возвращать понятные сообщения об ошибках при неверных данных |
| Присвоить параметр | Присвоить проверенные данные параметрам функции, обеспечивая автодополнение в редакторе |
| Сгенерировать документацию | Автоматически создавать JSON Schema, которая появляется в документации API |
Использовать атрибуты модели
Внутри функции операции пути можно получить доступ ко всем атрибутам модели так же, как при работе с обычным объектом Python:
Пример
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
@app.post("/items/")
async def create_item(item: Item):
# Прямой доступ к атрибутам модели
item_dict = item.model_dump() # Метод сериализации Pydantic v2
if item.tax:
# Рассчитать цену с учетом налога
price_with_tax = item.price + item.tax
item_dict.update({"price_with_tax": price_with_tax})
return item_dict
Использование Pydantic v2
model_dump()Заменяет v1dict()метод для сериализации данных модели.model_dump()Вернуть словарь, содержащий все поля модели.
Тело запроса + параметры пути
Вы можете объявить параметры пути и тело запроса одновременно, и FastAPI автоматически получит данные из нужных мест:
Пример
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
# Использование одновременно параметров пути и тела запроса
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
return {"item_id": item_id, "item_name": item.name}
Правила распознавания FastAPI:
item_idв пути{item_id}появляется в -> параметр путиitemТип является моделью Pydantic -> тело запроса
Тело запроса + параметры пути + параметры запроса
Все три можно использовать одновременно:
Пример
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
# Использование параметров пути, параметров запроса и тела запроса одновременно
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, q: str | None = None):
result = {"item_id": item_id, **item.model_dump()}
if q:
result.update({"q": q})
return result
Полные правила распознавания параметров FastAPI:
| Условие распознавания | Источник параметра |
|---|---|
Имена параметров в пути{}объявлен в | Параметр пути |
Параметр имеет один тип (int、str、boolи т.д.) | Параметр запроса |
| Если тип параметра — модель Pydantic | тело запроса |
Итог
Ключевые моменты тела запроса:
- Использование Pydantic
BaseModelОпределение структуры тела запроса - Поля со значениями по умолчанию необязательны; поля без значений по умолчанию обязательны.
- Тело запроса можно использовать вместе с параметрами пути и параметрами запроса.
- FastAPI автоматически выполняет валидацию данных, преобразование типов и генерацию документации.
- Использование Pydantic v2
model_dump()Выполнить сериализацию