Pydantic Schema — Validation et sérialisation des données

Dans ce chapitre, vous découvrirez Pydantic Schema et comprendrez sa séparation des responsabilités par rapport aux modèles ORM — c'est la fonctionnalité la plus centrale de FastAPI.


Pourquoi avons-nous besoin de schémas ?

Les modèles ORM (models.py) définissent la structure de la base de données, mais ne peuvent pas être utilisés directement pour la validation des requêtes/réponses d'API.

Raison : les modèles ORM contiennent une logique spécifique à la base de données (comme les relations), et vous ne voulez pas exposer tous les champs à l'API.

Pydantic SchemaC'est une classe de données pure, spécifiquement responsable de la validation et de la sérialisation des entrées/sorties de l'API.

La relation entre ces trois :

客户端 → [Pydantic Schema 校验] → 路由函数 → [ORM 模型] → 数据库
客户端 ← [Pydantic Schema 序列化] ← 路由函数 ← [ORM 模型] ← 数据库

Bases de Pydantic Schema

Pydantic V2 est le moteur de données de FastAPI, définissant les structures de données via des indications de type.

Exemple

from pydantic import BaseModel, ConfigDict

class ItemCreate(BaseModel):
    """Schéma pour la création de requêtes"""
    name: str
    price: float                       # Valide automatiquement le type
    is_offer: bool = False             # Avec des valeurs par défaut (champs optionnels)

class ItemResponse(BaseModel):
    """Schéma de réponse"""
    id: int
    name: str
    price: float

    # Approche V2 : activer le mode ORM, permettant une conversion directe depuis les objets ORM.
    model_config = ConfigDict(from_attributes=True)

Définir le schéma pour le blog

Exemple

# Chemin du fichier : schemas.py
from pydantic import BaseModel, ConfigDict
from datetime import datetime
from typing import Optional

# ====== Schéma de catégorie ======
class CategoryBase(BaseModel):
    name: str
    slug: str

class CategoryResponse(CategoryBase):
    id: int
    model_config = ConfigDict(from_attributes=True)

# ====== Schéma d’article ======
class PostBase(BaseModel):
    title: str
    slug: str
    summary: Optional[str] = None      # Optional = peut être None
    content: str
    category_id: int

class PostCreate(PostBase):
    """Schéma du corps de requête pour créer un article."""
    pass                               # Hérite directement de PostBase, les champs sont identiques.

class PostUpdate(BaseModel):
    """Mettre à jour un article (tous les champs facultatifs)"""
    title: Optional[str] = None
    slug: Optional[str] = None
    summary: Optional[str] = None
    content: Optional[str] = None
    category_id: Optional[int] = None

class PostResponse(PostBase):
    """Schéma de réponse renvoyé au client."""
    id: int
    created_at: datetime
    updated_at: datetime
    category: CategoryResponse         # Schéma imbriqué : Renvoyer les informations de catégorie

    model_config = ConfigDict(from_attributes=True)
    from_attributes=True indique à Pydantic : ce schéma peut être créé à partir d'objets ORM

Dans Pydantic V2,model_config = ConfigDict(from_attributes=True)Remplace celle de la V1class Config: orm_mode = TrueCette configuration vous permet de construire directement un schéma Pydantic à partir d'objets ORM SQLAlchemy :PostResponse.model_validate(post_orm_obj)。


Utilisation de schémas dans les routes

Exemple

# Chemin du fichier : routers/posts.py (exemple de création d'une route POST)
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session
from database import get_db
from models import Post
from schemas import PostCreate, PostResponse

router = APIRouter(prefix="/posts", tags=["Article"])

# Après avoir déclaré response_model=PostResponse :
# 1. FastAPI convertit automatiquement les objets ORM en schéma (sérialisation)
# 2. La documentation de l'API affiche automatiquement la structure de la réponse
@router.post("/", response_model=PostResponse, status_code=201)
def create_post(post_data: PostCreate, db: Session = Depends(get_db)):
    """
Créer un nouvel article
- post_data : corps de la requête, FastAPI valide automatiquement par rapport au schéma PostCreate
db : session de base de données injectée via Depends(get_db)
    """

    post = Post(**post_data.model_dump())  # model_dump() convertit le schéma en dict
    db.add(post)
    db.commit()
    db.refresh(post)                       # Rafraîchir et récupérer l'ID auto-incrémenté de la base de données
    return post                            # FastAPI sérialise automatiquement en utilisant PostResponse.

response_modelC'est l'une des fonctionnalités les plus puissantes de FastAPI. Une fois déclaré, FastAPI va : 1. filtrer automatiquement les champs des objets ORM qui ne sont pas déclarés dans le schéma ; 2. convertir automatiquement des types tels que datetime en chaînes JSON ; 3. générer une documentation OpenAPI précise.


Comparaison entre modèle ORM et schéma Pydantic

AspectModèle ORM SQLAlchemySchéma Pydantic
Emplacement de la définitionmodels.pyschemas.py
classe de baseBase (DeclarativeBase)BaseModel (Pydantic)
ResponsabilitésDéfinir les structures et relations des tables de base de donnéesDéfinir les formats d'entrée/sortie de l'API et les règles de validation.
Relation avec la base de donnéesCorrespond directement aux tables de la base de donnéesIl ne se soucie pas de la base de données, seulement du contrat d'API.
Déclaration de champColumn(Integer, ...)Indications de type Python : int, str
sérialisationNe peut pas être converti directement en JSON.model_dump() intégré et sérialisation JSON
Sens de conversionORM → Schéma : model_validate(obj)Schéma → ORM : Model(**schema.model_dump())

Résumé du chapitre

Dans ce chapitre, vous avez maîtrisé les concepts les plus fondamentaux des schémas Pydantic de FastAPI : BaseModel pour définir les schémas de requête/réponse, from_attributes=True pour activer le mode ORM, response_model pour sérialiser automatiquement les objets ORM, et le principe de séparation des responsabilités entre les schémas et les modèles ORM.

C’est l’essence de l’architecture pilotée par les types de FastAPI — définissez d’abord la forme des données, et les routes et la documentation sont générées automatiquement.

autres extensions