Тело запроса 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 fastapi import FastAPI
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 fastapi import FastAPI
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 v2model_dump()Заменяет v1dict()метод для сериализации данных модели.model_dump()Вернуть словарь, содержащий все поля модели.


Тело запроса + параметры пути

Вы можете объявить параметры пути и тело запроса одновременно, и FastAPI автоматически получит данные из нужных мест:

Пример

from fastapi import 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 fastapi import 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, 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тело запроса

Итог

Ключевые моменты тела запроса:

  • Использование PydanticBaseModelОпределение структуры тела запроса
  • Поля со значениями по умолчанию необязательны; поля без значений по умолчанию обязательны.
  • Тело запроса можно использовать вместе с параметрами пути и параметрами запроса.
  • FastAPI автоматически выполняет валидацию данных, преобразование типов и генерацию документации.
  • Использование Pydantic v2model_dump()Выполнить сериализацию
Другие расширения