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 :
| Objectif | Description |
|---|---|
| Validation du corps de requête | Valider 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éponse | Convertir automatiquement les données du modèle en réponses JSON |
| Documentation automatique | Les champs, types et règles de validation du modèle apparaissent automatiquement dans la documentation de l'API |
| Prise en charge de l'éditeur | Les 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
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 :
| Fields | Méthode de déclaration | Obligatoire ? |
|---|---|---|
name | name: str | Requis |
description | description: str | None = None | Optional |
price | price: float | Requis |
tax | tax: float | None = None | Optional |
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 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
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 v2
model_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
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éthodes | v2 (Recommandé) | v1 (obsolète) | Description |
|---|---|---|---|
| Sérialiser en dictionnaire | item.model_dump() | item.dict() | Convertir un modèle en dictionnaire Python |
| Sérialiser en JSON | item.model_dump_json() | item.json() | Convertir un modèle en chaîne JSON |
| Créer à partir d'un dictionnaire | Item.model_validate(data) | Item.parse_obj(data) | Créer et valider un modèle à partir d'un dictionnaire |
| Créer à partir de JSON | Item.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 JSON | Item.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
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
# 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 :
- Utilisation
BaseModelDé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 v2
model_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