Поля тела запроса и вложенные модели в FastAPI
Внутри модели Pydantic можно использоватьFieldчтобы объявлять правила валидации и метаданные для полей, а также вкладывать модели для обработки сложных структур данных JSON.
Использование Field для объявления валидации поля
Используется в функциях операций путиQuery、PathСпособ объявления валидации такой же; внутри моделей Pydantic вы используетеFieldОбъявление валидации поля:
Пример
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 | меньше или равно | |
| metadata | title | Заголовок поля |
description | Описание поля |
Примечание
FieldfrompydanticИмпорт, а не fromfastapiИмпорт. ЭтоQuery、Pathи т. д. fromfastapiИмпорт отличается.
Поле типа список
Вы можете объявить поле как список и указать тип элемента:
Пример
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Тип:
Пример
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set() # Автоматически удаляет повторяющиеся теги
Даже если запрос содержит повторяющиеся теги, они будут автоматически дедуплицированы в ответе.
Вложенная модель
Тип поля модели Pydantic может быть другой моделью Pydantic, с поддержкой вложенности на любую глубину:
Пример
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 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 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 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Тело запроса типа:
Пример
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)。
Итог
- Использование Pydantic
FieldДобавление валидации и метаданных к полям модели list[str]、set[str]Такие типы коллекций можно объявлять как поля list/set- Модели могут быть вложенными, поддерживая JSON-структуры любой глубины
HttpUrlа другие специальные типы автоматически валидируют формат- Обычные списки и произвольные словари также можно использовать в качестве типов тела запроса