Corps de requête FastAPI

Le corps de requête correspond aux données envoyées par le client à l'API. Lorsque vous devez recevoir des données JSON du client, utilisez le corps de requête pour les transmettre. FastAPI utilise des modèles Pydantic pour déclarer la structure du corps de requête, en effectuant automatiquement la validation des données, la conversion et la génération de documentation.


La différence entre le corps de requête et les paramètres de requête

Méthodes de transfert de donnéesPositionScénarios applicablesMéthodes HTTP
Paramètre de cheminChemin d'URL/items/5Identifier la ressourceGET, PUT, DELETE, etc.
Paramètre de requêteDans l'URL?key=valueParamètres optionnels tels que le filtrage et la paginationPrincipalement GET
corps de requêteLes données JSON de la requêteSoumission de données complexesPOST, PUT, PATCH

L'envoi de données doit utiliserPOST(le plus courant),PUT、DELETEouPATCHBien que FastAPI prenne techniquement en charge les requêtes GET transportant un corps de requête, cela ne respecte pas les spécifications HTTP, et Swagger UI n'affichera pas la documentation du corps de requête pour les requêtes GET.


Déclarer le corps de la requête avec un modèle Pydantic

Importer BaseModel

from pydantic import BaseModel

2. Créer un modèle de données

Définir une classe héritantBaseModelPour la classe, déclarez tous les attributs en utilisant les types standard de Python :

Exemple

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


# Définir le modèle de données du corps de la requête
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


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

Les règles pour déterminer si les attributs sont requis sont les mêmes que pour les paramètres de requête :

  • Les attributs avec des valeurs par défaut sont facultatifs (par ex.,description、tax)
  • Les attributs sans valeur par défaut sont requis (par ex.,name、price)

Les JSON suivants sont tous des corps de requête valides :

// 包含所有字段
{
    "name": "Foo",
    "description": "可选描述",
    "price": 45.2,
    "tax": 3.5
}

// 省略可选字段
{
    "name": "Foo",
    "price": 45.2
}

La gestion du corps de la requête par FastAPI

Rien qu'en déclarant les types Python, FastAPI peut automatiquement faire ce qui suit :

FonctionnalitésDescription
Lire le corps de la requêteLire les données de la requête au format JSON
Conversion de typeConvertir les données vers les types déclarés (par exemple, chaîne en float)
Vérification des donnéesValider les données et renvoyer des messages d'erreur clairs lorsqu'elles sont invalides
Affecter le paramètreAffecter les données validées aux paramètres de la fonction, en fournissant l'autocomplétion de l'éditeur
Générer la documentationGénérer automatiquement un JSON Schema, qui apparaît dans la documentation de l'API

Utiliser les attributs du modèle

À l'intérieur de la fonction d'opération de chemin, vous pouvez accéder à tous les attributs du modèle comme vous le feriez sur un objet Python normal :

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):
    # Accéder directement aux attributs du modèle
    item_dict = item.model_dump()  # Pydantic v2 serialization method
    if item.tax:
        # Calculer le prix TTC
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

Utilisation de Pydantic v2model_dump()Remplace la v1dict()méthode pour sérialiser les données du modèle.model_dump()Renvoie un dictionnaire contenant tous les champs du modèle.


Corps de requête + paramètres de chemin

Vous pouvez déclarer des paramètres de chemin et un corps de requête en même temps, et FastAPI récupérera automatiquement les données aux bons endroits :

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


# Utilisation à la fois des paramètres de chemin et du corps de requête
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, "item_name": item.name}

Règles de reconnaissance de FastAPI :

  • item_iddans le chemin{item_id}apparaît dans -> paramètre de chemin
  • itemLe type est un modèle Pydantic -> corps de la requête

Corps de la requête + paramètres de chemin + paramètres de requête

Les trois peuvent être utilisés simultanément :

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


# Utilisation simultanée des paramètres de chemin, des paramètres de requête et du corps de la requête
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, q: str | None = None):
    result = {"item_id": item_id, **item.model_dump()}
    if q:
        result.update({"q": q})
    return result

Règles complètes de reconnaissance des paramètres de FastAPI :

Condition de reconnaissanceSource du paramètre
Noms des paramètres dans le chemin{}déclaré dansParamètre de chemin
Le paramètre est d'un type simple (int、str、booletc.)Paramètre de requête
Si le type du paramètre est un modèle Pydanticcorps de requête

Résumé

Points clés du corps de la requête :

  • En utilisant PydanticBaseModelDéfinir la structure du corps de la requête
  • Les champs avec des valeurs par défaut sont facultatifs ; les champs sans valeur par défaut sont obligatoires.
  • Le corps de la requête peut être utilisé conjointement avec les paramètres de chemin et les paramètres de requête.
  • FastAPI effectue automatiquement la validation des données, la conversion de type et la génération de la documentation.
  • Utilisation de Pydantic v2model_dump()Effectuer la sérialisation
autres extensions