Skip to content

От переводчика

Это машинный перевод (DeepSeek) статьи https://fastapi.tiangolo.com/tutorial/body-nested-models/

Версия от 03.09.2026

Неочевидных моментов в уроке не обнаружено, но я рад сообщить, что дополнил базу инструмента для импорта модулей и классов в python классами, использующимися в уроке.

Подпишитесь на канал "Изучаем FastAPI", чтобы ссылки на инструмент работала.

 

Перевод прочих разделов документации буду по мере сил делать.

Обо мне

Тело запроса — вложенные модели

С FastAPI вы можете определять, валидировать, документировать и использовать сколь угодно глубоко вложенные модели (благодаря Pydantic).

Поля-списки

Вы можете определить атрибут как подтип. Например, Python list:

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 = []


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

Это сделает tags списком, хотя тип элементов списка не объявлен.

Поля-списки с параметром типа

Но в Python есть специальный способ объявления списков с внутренними типами, или «параметрами типа»:

Объявление list с параметром типа

Чтобы объявить типы, имеющие параметры типа (внутренние типы), такие как list, dict, tuple, передайте внутренний тип(ы) как «параметры типа», используя квадратные скобки: [ и ]

my_list: list[str]

Это стандартный синтаксис Python для объявления типов.

Используйте тот же стандартный синтаксис для атрибутов модели с внутренними типами.

Итак, в нашем примере мы можем сделать tags именно «списком строк»:

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.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

Типы-множества

Но затем мы подумаем и поймём, что теги не должны повторяться, скорее всего, это будут уникальные строки.

И в Python есть специальный тип данных для множеств уникальных элементов — set.

Тогда мы можем объявить tags как множество строк:

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: set[str] = set()


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

С этим, даже если вы получите запрос с дублирующимися данными, они будут преобразованы в множество уникальных элементов.

И всякий раз, когда вы выводите эти данные, даже если в источнике были дубликаты, они будут выведены как множество уникальных элементов.

И это также будет соответствующим образом аннотировано / задокументировано.

Вложенные модели

Каждый атрибут модели Pydantic имеет тип.

Но этот тип сам по себе может быть другой моделью Pydantic.

Таким образом, вы можете объявлять глубоко вложенные JSON «объекты» с конкретными именами атрибутов, типами и валидациями.

Всё это, произвольно вложенное.

Определение подмодели

Например, мы можем определить модель Image:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


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


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


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

Использование подмодели как типа

И затем мы можем использовать её как тип атрибута:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


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


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


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

Это будет означать, что FastAPI будет ожидать тело, похожее на:

{
    "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"
    }
}

Опять же, сделав только это объявление, с FastAPI вы получаете:

  • Поддержку редактора (автодополнение и т.д.), даже для вложенных моделей
  • Преобразование данных
  • Валидацию данных
  • Автоматическую документацию

Специальные типы и валидация

Помимо обычных единичных типов, таких как str, int, float и т.д., вы можете использовать более сложные единичные типы, которые наследуются от str.

Чтобы увидеть все доступные вам варианты, ознакомьтесь с Обзором типов Pydantic. Некоторые примеры вы увидите в следующей главе.

Например, как в модели Image у нас есть поле url, мы можем объявить его как экземпляр HttpUrl из Pydantic вместо str:

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()
    image: Image | None = None


@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

Строка будет проверена на то, что она является допустимым URL, и задокументирована в JSON Schema / OpenAPI как таковая.

Атрибуты со списками подмоделей

Вы также можете использовать модели Pydantic как подтипы list, set и т.д.:

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.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

Это будет ожидать (преобразовывать, валидировать, документировать и т.д.) JSON-тело вида:

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

Примечание

Обратите внимание, что теперь ключ images содержит список объектов изображений.

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

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

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]


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

Примечание

Обратите внимание, что Offer содержит список Item, которые, в свою очередь, содержат необязательный список Image

Тела из чистых списков

Если значение верхнего уровня JSON-тела, которое вы ожидаете, является JSON array (Python list), вы можете объявить тип в параметре функции так же, как в моделях Pydantic:

images: list[Image]

как в:

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


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


@app.post("/images/multiple/")
async def create_multiple_images(images: list[Image]):
    return images

Поддержка редактора повсюду

И вы получаете поддержку редактора повсюду.

Даже для элементов внутри списков:

Вы не получили бы такую поддержку редактора, если бы работали напрямую с dict вместо моделей Pydantic.

Но вам не нужно о них беспокоиться: входящие dict автоматически преобразуются, и ваш вывод также автоматически преобразуется в JSON.

Тела из произвольных dict

Вы также можете объявить тело как dict с ключами одного типа и значениями другого типа.

Таким образом, вам не нужно заранее знать, какими будут допустимые имена полей/атрибутов (как это было бы в случае с моделями Pydantic).

Это было бы полезно, если вы хотите принимать ключи, которые вы ещё не знаете.


Другой полезный случай — когда вы хотите иметь ключи другого типа (например, int).

Именно это мы здесь и рассмотрим.

В этом случае вы примете любой dict, если у него есть ключи int со значениями float:

from fastapi import FastAPI

app = FastAPI()


@app.post("/index-weights/")
async def create_index_weights(weights: dict[int, float]):
    return weights

Совет

Имейте в виду, что JSON поддерживает в качестве ключей только str.

Но Pydantic имеет автоматическое преобразование данных.

Это означает, что даже если ваши API-клиенты могут отправлять в качестве ключей только строки, при условии, что эти строки содержат чистые целые числа, Pydantic преобразует их и провалидирует.

И dict, который вы получите как weights, фактически будет иметь ключи int и значения float.

Итог

С FastAPI вы получаете максимальную гибкость, предоставляемую моделями Pydantic, сохраняя при этом ваш код простым, коротким и элегантным.

Но со всеми преимуществами:

  • Поддержка редактора (автодополнение повсюду!)
  • Преобразование данных (также известное как парсинг / сериализация)
  • Валидация данных
  • Документирование схемы
  • Автоматическая документация