Champs du corps de requête FastAPI et modèles imbriqués

Dans un modèle Pydantic, vous pouvez utiliserFieldpour déclarer des règles de validation et des métadonnées pour les champs, et vous pouvez également imbriquer des modèles pour gérer des structures de données JSON complexes.


Utilisation de Field pour déclarer la validation des champs

Utilisé dans les fonctions d'opération de cheminQuery、PathLa façon de déclarer la validation est la même ; dans les modèles Pydantic, vous utilisezFieldDéclarer la validation des champs :

Exemple

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="Nom du produit")  # Requis, 1 à 100 caractères
    description: str | None = Field(default=None, max_length=300, description="Description du produit")  # Facultatif
    price: float = Field(gt=0, description="Prix du produit")  # Requis, doit être supérieur à 0
    tax: float | None = Field(default=None, ge=0, description="Taxe")  # Facultatif, >= 0


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

FieldParamètres de validation pris en charge :

Type de paramètreParamètreDescription
Validation de chaînemin_lengthLongueur minimale
max_lengthLongueur maximale
patternCorrespondance d'expression régulière
Validation numériquegtsupérieur à
gesupérieur ou égal à
ltinférieur à
leinférieur ou égal à
metadatatitleTitre du champ
descriptionDescription du champ

RemarqueFieldfrompydanticImport, plutôt que fromfastapiImport. Ceci estQuery、Pathetc. fromfastapiImport diffère.


Champ de type liste

Vous pouvez déclarer un champ comme une liste et spécifier le type des éléments :

Exemple

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] = []  # Liste de chaînes, liste vide par défaut


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

Exemple de corps de requête :

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

Utilisez Set pour dédupliquer

Si les tags ne doivent pas être dupliqués, utilisezsetType :

Exemple

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()  # Supprimer automatiquement les tags en double

Même si la requête contient des tags en double, ils seront automatiquement dédupliqués dans la réponse.


Modèle imbriqué

Le type d'un champ d'un modèle Pydantic peut être un autre modèle Pydantic, permettant une imbrication à n'importe quelle profondeur :

Exemple

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


# Sous-modèle : Image
class Image(BaseModel):
    url: HttpUrl      # Valide automatiquement s'il s'agit d'une URL valide
    name: str


# Modèle principal : Product, inclut le sous-modèle image
class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    image: Image | None = None  # Informations facultatives sur l'image


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

Structure correspondante du corps de requête :

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

Sous-modèle dans une liste

Vous pouvez placer des sous-modèles dans une liste :

Exemple

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  # Liste d'images


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

Corps de requête correspondant :

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

Modèles profondément imbriqués

Vous pouvez définir des structures imbriquées de n'importe quelle profondeur :

Exemple

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 contient plusieurs Items, et un Item contient plusieurs Images


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

Corps de requête de type liste pure

Si la couche la plus externe du corps de requête est un tableau JSON, vous pouvez déclarer directement un type liste dans le paramètre de la fonction :

Exemple

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


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


# Le corps de la requête est directement une liste d'Images
@app.post("/images/multiple/")
async def create_multiple_images(images: list[Image]):
    return images

Corps de requête composé d'un dict arbitraire

Lorsque vous devez recevoir des données de dictionnaire avec des noms de clés incertains, vous pouvez déclarerdictCorps de requête de type :

Exemple

from fastapi import FastAPI

app = FastAPI()


# Recevoir un dict avec des clés int et des valeurs float
@app.post("/index-weights/")
async def create_index_weights(weights: dict[int, float]):
    return weights

Exemple de corps de requête :

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

JSON ne prend en charge que les clés de type chaîne, mais Pydantic convertira automatiquement les clés de chaîne vers le type déclaré (tel que leint)。


Résumé

  • En utilisant PydanticFieldAjouter une validation et des métadonnées aux champs du modèle
  • list[str]、set[str]Les types de collection tels que ceux-ci peuvent être déclarés comme champs list/set
  • Les modèles peuvent être imbriqués, prenant en charge des structures JSON de n'importe quelle profondeur
  • HttpUrlet d'autres types spéciaux valident automatiquement le format
  • Les listes simples et les dictionnaires arbitraires peuvent également être utilisés comme types de corps de requête
autres extensions