Modèle Pydantic de FastAPI

Pydantic est une dépendance essentielle de FastAPI, utilisée pour la validation et la sérialisation des données. Il vous permet de définir des modèles de données à l'aide d'annotations de type Python standard, en gérant automatiquement la validation des données, la conversion de type et la génération de documentation.


Qu'est-ce que Pydantic

Pydantic est une bibliothèque de validation de données Python. Sa philosophie centrale est :Définir des structures de données avec des annotations de type Python, et Pydantic gère automatiquement la validation et la conversionDans FastAPI, Pydantic est principalement utilisé pour :

ObjectifDescription
Validation du corps de requêteValider automatiquement si les données JSON envoyées par les clients sont conformes à la définition du modèle
Sérialisation du corps de réponseConvertir automatiquement les données du modèle en réponses JSON
Documentation automatiqueLes champs, types et règles de validation du modèle apparaissent automatiquement dans la documentation de l'API
Prise en charge de l'éditeurLes attributs du modèle bénéficient d'une autocomplétion complète dans l'éditeur

Définir des modèles Pydantic

Créer un héritageBaseModelclasses qui déclarent des champs à l'aide de types Python standard :

Exemple

from pydantic import BaseModel


class Item(BaseModel):
    name: str               # Requis : Nom du produit
    description: str | None = None  # Facultatif : description du produit
    price: float            # Obligatoire : prix du produit
    tax: float | None = None        # Facultatif : taxe

Qu'un champ soit obligatoire dépend de la présence d'une valeur par défaut :

FieldsMéthode de déclarationObligatoire ?
namename: strRequis
descriptiondescription: str | None = NoneOptional
priceprice: floatRequis
taxtax: float | None = NoneOptional

Utiliser des modèles Pydantic

En tant que corps de requête

L'utilisation la plus courante consiste à déclarer un modèle comme paramètre d'une fonction d'opération de chemin :

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


@app.post("/items/")
async def create_item(item: Item):
    # FastAPI valide automatiquement le corps de la requête et, une fois la validation réussie, l'attribue au paramètre item
    return item

Accéder aux données du modèle et les manipuler

Exemple

@app.post("/items/")
async def create_item(item: Item):
    # Accéder aux attributs du modèle
    print(item.name)       # Accéder directement aux attributs
    print(item.price)      # L'éditeur fournit l'autocomplétion

    # Sérialiser en dictionnaire
    item_dict = item.model_dump()
    print(item_dict)       # {"name": "Foo", "description": None, "price": 45.2, "tax": None}

    # Sérialiser en chaîne JSON
    item_json = item.model_dump_json()
    print(item_json)       # '{"name":"Foo","description":null,"price":45.2,"tax":null}'

    return item_dict

Utilisation de Pydantic v2model_dump()etmodel_dump_json()Remplace la méthode de v1dict()etjson()La nouvelle méthode a de meilleures performances (implémentée en Rust sous le capot).


Exemple de validation de modèle

Lorsque les données envoyées par un client ne sont pas conformes à la définition du modèle, FastAPI renvoie des erreurs de validation détaillées :

Exemple

# Le client a envoyé des données auxquelles il manque des champs obligatoires
POST /items/
{
    "description": "nom et prix manquants"
}

# Erreur de validation de la réponse FastAPI
{
    "detail": [
        {
            "type": "missing",
            "loc": ["body", "name"],
            "msg": "Champ requis",
            "input": {"description": "nom et prix manquants"}
        },
        {
            "type": "missing",
            "loc": ["body", "price"],
            "msg": "Champ requis",
            "input": {"description": "nom et prix manquants"}
        }
    ]
}

Si des données de type incorrect sont envoyées :

// price 应该是数字,但传了字符串
{
    "name": "Foo",
    "price": "not a number"
}

// FastAPI 返回的错误
{
    "detail": [
        {
            "type": "float_parsing",
            "loc": ["body", "price"],
            "msg": "Input should be a valid number, unable to parse string as a number",
            "input": "not a number"
        }
    ]
}

Méthodes courantes de Pydantic v2

Méthodesv2 (Recommandé)v1 (obsolète)Description
Sérialiser en dictionnaireitem.model_dump()item.dict()Convertir un modèle en dictionnaire Python
Sérialiser en JSONitem.model_dump_json()item.json()Convertir un modèle en chaîne JSON
Créer à partir d'un dictionnaireItem.model_validate(data)Item.parse_obj(data)Créer et valider un modèle à partir d'un dictionnaire
Créer à partir de JSONItem.model_validate_json(json_str)Item.parse_raw(json_str)Créer un modèle à partir d'une chaîne JSON
Obtenir le schéma JSONItem.model_json_schema()Item.schema()Obtention du schéma JSON du modèle

Configuration du modèle (model_config)

Utilisation de Pydantic v2model_configRemplace la méthode de v1ConfigClasse interne :

Exemple

from pydantic import BaseModel, ConfigDict


class Item(BaseModel):
    name: str
    price: float

    # Méthode de configuration de Pydantic v2
    model_config = ConfigDict(
        json_schema_extra={  # Afficher des exemples dans la documentation de l'API
            "examples": [
                {
                    "name": "Foo",
                    "price": 35.4
                }
            ]
        }
    )

Dans Pydantic v2,orm_mode = Trueremplacé parfrom_attributes = True,schema_extraremplacé parjson_schema_extra,allow_population_by_field_nameremplacé parpopulate_by_name。


Héritage de modèle

Les modèles Pydantic prennent en charge l'héritage, ce qui facilite la création de modèles d'entrée et de modèles de sortie :

Exemple

from pydantic import BaseModel, EmailStr


# Modèle de base
class UserBase(BaseModel):
    username: str       # Requis
    email: EmailStr     # Requis, valide automatiquement le format de l'e-mail
    full_name: str | None = None  # Facultatif


# Modèle d'entrée pour créer un utilisateur (y compris le mot de passe)
class UserCreate(UserBase):
    password: str       # Requis


# Modèle de sortie pour renvoyer les informations utilisateur (ne comprend pas le mot de passe)
class UserOut(UserBase):
    id: int             # Généré par le serveur


# Exemple d'utilisation
@app.post("/users/", response_model=UserOut)
async def create_user(user: UserCreate):
    # La fonction reçoit UserCreate (avec mot de passe), mais la réponse utilise UserOut (sans mot de passe)
    # Ainsi, le mot de passe n'apparaîtra pas dans la réponse de l'API.
    return {"id": 1, **user.model_dump(exclude={"password"})}

Utiliser des modèles d'entrée et de sortie différents est un moyen important de protéger les données sensibles. Ne renvoyez jamais de champs sensibles tels que les mots de passe dans les réponses de l'API.


Résumé

Points clés des modèles Pydantic :

  • UtilisationBaseModelDéfinissez des modèles de données avec des types Python standard en déclarant les champs
  • Les champs avec des valeurs par défaut sont facultatifs, les champs sans valeur par défaut sont obligatoires
  • Utilisation de la v2model_dump()、model_validate()et d'autres nouvelles méthodes
  • Créez différents modèles d'entrée/sortie via l'héritage de modèles pour protéger les données sensibles
  • Toute la validation et la documentation sont automatiques — il suffit de déclarer les types une fois
autres extensions