Validation des paramètres de requête FastAPI
FastAPI vous permet de déclarer des règles de validation et des métadonnées supplémentaires pour les paramètres de requête, telles que des limites de longueur de chaîne, la correspondance regex, etc. Grâce à cette fonctionnalitéQueryetAnnotated, vous pouvez améliorer la validation des paramètres sans modifier la logique de la fonction.
Validation de base
L'exemple suivant concerne les paramètres de requêteqAjouter une limite de longueur maximale:
Exemple
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
# Utiliser Annotated + Query pour ajouter une validation
q: Annotated[str | None, Query(max_length=50)] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Explication du code :
| Partie | Description |
|---|---|
Annotated[str | None, ...] | Annotations de type, significationqPeut être une chaîne de caractères ou None |
Query(max_length=50) | Règles de validation,qLa longueur maximale est de 50 caractères |
= None | Valeur par défaut, ce qui rend le paramètre facultatif |
FastAPI recommande d'utiliser
AnnotatedDéclarer la validation d'une manière, plutôt que d'utiliserQuerycomme valeur par défaut. Parce queAnnotatedDans cette approche, la valeur par défaut de la fonction est la vraie valeur par défaut, ce qui est plus intuitif en Python et mieux pris en charge par les éditeurs et les outils de vérification de type.
Ajout de validations supplémentaires
Vous pouvez ajouter plusieurs règles de validation simultanément :
Exemple
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
# Limiter également la longueur minimale, la longueur maximale et l'expression régulière
q: Annotated[str | None, Query(min_length=3, max_length=50, pattern="^fixedquery$")] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Paramètres de validation de chaîne :
| Paramètre | Type | Description |
|---|---|---|
min_length | int | Longueur minimale |
max_length | int | Longueur maximale |
pattern | str | Correspondance d'expression régulière |
Expression régulière^fixedquery$Signification :
^-- Doit commencer par les caractères suivantsfixedquery-- La valeur doit être exactement égale àfixedquery$-- Fin ici ; aucun autre caractère ne peut suivre.
Validation avec des valeurs par défaut
Vous pouvez définir à la fois une valeur par défaut et des règles de validation pour un paramètre de requête :
Exemple
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
# La valeur par défaut est "fixedquery", et la longueur minimale est 3
q: Annotated[str, Query(min_length=3)] = "fixedquery",
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Valeur par défaut de tout type (y compris non-
Nonevalue) rendra le paramètre optionnel. Sans valeur par défaut et sansQuery(default=...)les paramètres sont obligatoires.
Paramètre obligatoire
UtilisationQuery, si vous ne déclarez pas de valeur par défaut, le paramètre est obligatoire :
Exemple
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
# Aucune valeur = None, donc q est un paramètre obligatoire.
q: Annotated[str, Query(min_length=3)],
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
results.update({"q": q})
return results
Obligatoire mais peut être None
Parfois, vous avez besoin que le client passe une valeur, mais la valeur peut êtreNone:
Exemple
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
# Le client doit fournir le paramètre q, mais la valeur peut être None
q: Annotated[str | None, Query(min_length=3)],
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Liste de paramètres de requête / valeurs multiples
UtilisationQueryVous pouvez déclarer des paramètres de requête qui reçoivent plusieurs valeurs :
Exemple
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
# q peut apparaître plusieurs fois dans l'URL, et les valeurs seront collectées sous forme de liste
q: Annotated[list[str] | None, Query()] = Aucune,
):
query_items = {"q": q}
return query_items
Visitezhttp://127.0.0.1:8000/items/?q=foo&q=bar, renvoie :
{"q": ["foo", "bar"]}
Pour déclarer le type comme
listparamètres de requête, vous devez utiliser explicitementQuery(), sinon FastAPI l'interprétera comme le corps de la requête.
Déclarer des métadonnées
QueryIl prend également en charge l'ajout de métadonnées aux paramètres ; ces informations apparaîtront dans la documentation de l'API :
Exemple
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Annotated[str | None, Query(
title="query string", # Titre du paramètre
description="Chaîne de requête utilisée pour filtrer les produits", # Description du paramètre
min_length=3,
max_length=50,
alias="item-query", # Alias pour le nom du paramètre dans l'URL
deprecated=True, # Marquer comme obsolète
)] = Aucune,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Description du paramètre de métadonnées :
| Paramètre | Description | Cas d'utilisation |
|---|---|---|
alias | Alias pour le nom du paramètre dans l'URL | Le nom du paramètre contient un trait d'union (par ex.item-query), lorsqu'il ne s'agit pas d'un nom de variable Python valide |
title | Titre du paramètre | Afficher le titre du paramètre dans la documentation |
description | Description des paramètres | Afficher la description détaillée du paramètre dans la documentation |
deprecated | Marqué comme obsolète | Le paramètre peut toujours être utilisé, mais il sera marqué comme « deprecated » dans la documentation. |
include_in_schema | Indique s'il doit apparaître dans la documentation de l'API | Défini commeFalseParamètres pouvant être masqués |
Exclure des paramètres d'OpenAPI
Si un paramètre de requête ne doit pas apparaître dans la documentation de l'API :
Exemple
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
# hidden_query n'apparaîtra pas dans la documentation de l'API, mais il peut toujours être utilisé
hidden_query: Annotated[str | None, Query(include_in_schema=False)] = Aucune,
):
if hidden_query:
return {"hidden_query": hidden_query}
return {"items": [{"item_id": "Foo"}]}
Résumé
Points clés de la validation des paramètres de requête :
- Utilisation
Annotated+QueryDéclaration des règles de validation (approche recommandée) - Validation de chaîne :
min_length、max_length、pattern - Pas de valeur par défaut = paramètre obligatoire ; avec valeur par défaut = paramètre facultatif
aliasUtilisé pour les noms de paramètres dans les URL qui ne sont pas des noms de variables Python valides.deprecated=TrueMarquage des paramètres obsolètes- Utilisation
list[str]Recevoir plusieurs paramètres de requête portant le même nom