Поля тела запроса и вложенные модели в FastAPI

Внутри модели Pydantic можно использоватьFieldчтобы объявлять правила валидации и метаданные для полей, а также вкладывать модели для обработки сложных структур данных JSON.


Использование Field для объявления валидации поля

Используется в функциях операций путиQuery、PathСпособ объявления валидации такой же; внутри моделей Pydantic вы используетеFieldОбъявление валидации поля:

Пример

from typing import Annotated
from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str = Field(min_length=1, max_length=100, description="Название товара")  # Обязательно, 1-100 символов
    description: str | None = Field(default=None, max_length=300, description="Описание товара")  # Необязательно
    price: float = Field(gt=0, description="Цена товара")  # Обязательно, должно быть больше 0
    tax: float | None = Field(default=None, ge=0, description="Налог")  # Необязательно, >= 0


@app.post("/items/")
async def create_item(item: Item):
    return item

FieldПоддерживаемые параметры валидации:

Тип параметраПараметрОписание
Валидация строкmin_lengthМинимальная длина
max_lengthМаксимальная длина
patternСопоставление с регулярным выражением
Валидация чиселgtзнак больше
geбольше или равно
ltзнак меньше
leменьше или равно
metadatatitleЗаголовок поля
descriptionОписание поля

ПримечаниеFieldfrompydanticИмпорт, а не fromfastapiИмпорт. ЭтоQuery、Pathи т. д. fromfastapiИмпорт отличается.


Поле типа список

Вы можете объявить поле как список и указать тип элемента:

Пример

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
    tags: list[str] = []  # Список строк, по умолчанию пустой список


@app.post("/items/")
async def create_item(item: Item):
    return item

Пример тела запроса:

{
    "name": "Foo",
    "price": 42.0,
    "tags": ["rock", "metal", "bar"]
}

Используйте Set для удаления дубликатов

Если tags не должны дублироваться, используйтеsetТип:

Пример

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()  # Автоматически удаляет повторяющиеся теги

Даже если запрос содержит повторяющиеся теги, они будут автоматически дедуплицированы в ответе.


Вложенная модель

Тип поля модели Pydantic может быть другой моделью Pydantic, с поддержкой вложенности на любую глубину:

Пример

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


# Подмодель: Image
class Image(BaseModel):
    url: HttpUrl      # Автоматически проверяет, является ли он допустимым URL
    name: str


# Основная модель: Product, включает подмодель изображения
class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    image: Image | None = None  # Необязательная информация об изображении


@app.post("/items/")
async def create_item(item: Item):
    return item

Соответствующая структура тела запроса:

{
    "name": "Foo",
    "description": "The pretender",
    "price": 42.0,
    "tax": 3.2,
    "tags": ["rock", "metal", "bar"],
    "image": {
        "url": "http://example.com/baz.jpg",
        "name": "The Foo live"
    }
}

Подмодель в списке

Вы можете поместить подмодели в список:

Пример

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    images: list[Image] | None = None  # Список изображений


@app.post("/items/")
async def create_item(item: Item):
    return item

Соответствующее тело запроса:

{
    "name": "Foo",
    "price": 42.0,
    "images": [
        {"url": "http://example.com/baz.jpg", "name": "The Foo live"},
        {"url": "http://example.com/dave.jpg", "name": "The Baz"}
    ]
}

Глубоко вложенные модели

Вы можете определять вложенные структуры любой глубины:

Пример

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    images: list[Image] | None = None


class Offer(BaseModel):
    name: str
    description: str | None = None
    price: float
    items: list[Item]  # Offer содержит несколько объектов Item, а Item содержит несколько объектов Image


@app.post("/offers/")
async def create_offer(offer: Offer):
    return offer

Тело запроса — чистый список

Если самый внешний уровень тела запроса является JSON-массивом, можно напрямую объявить тип list в параметре функции:

Пример

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


# Тело запроса напрямую является списком Images
@app.post("/images/multiple/")
async def create_multiple_images(images: list[Image]):
    return images

Тело запроса, состоящее из произвольного dict

Когда вам нужно получить данные словаря с неизвестными именами ключей, вы можете объявитьdictТело запроса типа:

Пример

from fastapi import FastAPI

app = FastAPI()


# Получить dict с ключами int и значениями float
@app.post("/index-weights/")
async def create_index_weights(weights: dict[int, float]):
    return weights

Пример тела запроса:

{
    "1": 0.5,
    "2": 1.5,
    "3": 2.0
}

JSON поддерживает только ключи строкового типа, но Pydantic автоматически преобразует строковые ключи в объявленный тип (например,int)。


Итог

  • Использование PydanticFieldДобавление валидации и метаданных к полям модели
  • list[str]、set[str]Такие типы коллекций можно объявлять как поля list/set
  • Модели могут быть вложенными, поддерживая JSON-структуры любой глубины
  • HttpUrlа другие специальные типы автоматически валидируют формат
  • Обычные списки и произвольные словари также можно использовать в качестве типов тела запроса
Другие расширения