Paramètres de chemin FastAPI

Les paramètres de chemin sont les parties dynamiques du chemin de l'URL, utilisant des accolades pour{}les déclarer. FastAPI transmet automatiquement les paramètres de chemin à la fonction d'opération de chemin, et effectue la conversion et la validation des données en fonction des annotations de type.

Utilisation de base

Utilisez la syntaxe de chaîne formatée de Python pour déclarer les paramètres de chemin :

Exemple

from fastapi import FastAPI

app = FastAPI()

# {item_id} est un paramètre de chemin
@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

Visitezhttp://127.0.0.1:8000/items/5, renvoie :

{"item_id": 5}

Notez que la valeur renvoyéeitem_idest un entier5, pas une chaîne"5". FastAPI, à l'aide des annotations de type,item_id: intconvertit automatiquement la chaîne dans l'URL en un entier.

Konversi data

Lorsque vous déclarez le type commeintLorsque , FastAPI effectue automatiquement la conversion de type :

# 传入整数，正常工作
GET /items/3       -> {"item_id": 3}

# 传入非整数，返回校验错误
GET /items/foo     -> 错误：Input should be a valid integer

# 传入浮点数，同样报错
GET /items/4.2     -> 错误：Input should be a valid integer

Visitezhttp://127.0.0.1:8000/items/fooLorsque , les informations d'erreur de validation renvoyées par FastAPI :

{
  "detail": [
    {
      "type": "int_parsing",
      "loc": ["path", "item_id"],
      "msg": "Input should be a valid integer, unable to parse string as an integer",
      "input": "foo"
    }
  ]
}

Les messages d'erreur de validation de FastAPI sont très clairs et indiquent l'emplacement exact de l'erreur (loc), le type d'erreur (type) et la description de l'erreur (msg). C'est très utile lors du débogage.

Le type du paramètre de chemin

exceptint, vous pouvez également utiliser d'autres types standard de Python :

TypeDescriptionExemple d'URL
strString (type par défaut)/items/foo
intInteger/items/5
floatNombre à virgule flottante/items/5.5
boolValeur booléenne/items/true
uuid.UUIDUUID/items/3fa85f64-5717-4562-b3fc-2c963f66afa6

L'ordre des chemins est important

Lorsque plusieurs routes peuvent correspondre à la même URL, l'ordre de définition détermine le résultat de la correspondance. FastAPI fait correspondre les routes une par une dans l'ordre où elles sont définies, et la première route correspondante sera exécutée.

Exemple

from fastapi import FastAPI

app = FastAPI()

# Doit être défini avant /users/{user_id}
@app.get("/users/me")
async def read_user_me():
    """Obtenir les informations de l'utilisateur actuel"""
    return {"user_id": "the current user"}


@app.get("/users/{user_id}")
async def read_user(user_id: str):
    """Obtenir les informations de l'utilisateur par ID"""
    return {"user_id": user_id}

si vous mettez/users/mePlacez/users/{user_id}Après cela, accédez ensuite/users/meFastAPI considérera"me"Ouiuser_idla valeur, correspondant ainsi à la mauvaise fonction.

Les routes avec des chemins fixes doivent être placées avant les routes avec des paramètres de chemin dynamiques, sinon les paramètres dynamiques « avaleront » la valeur du chemin fixe.

Paramètres de chemin avec valeurs prédéfinies (Enum)

Lorsque vous devez restreindre un paramètre de chemin à plusieurs valeurs fixes, vous pouvez utiliser celui de PythonEnumType :

Exemple

from enum import Enum
from fastapi import FastAPI


# Créer une classe enum, héritant de str et d'Enum
class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    # Peut être comparé aux membres de l'énumération
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Le Deep Learning pour la victoire !"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN toutes les images"}

    return {"model_name": model_name, "message": "Prenez quelques résidus"}

Points clés des classes enum :

Points clésDescription
Héritagestrpour que la documentation de l'API reconnaisse le type de valeur comme une chaîne, garantissant un rendu correct
HéritageEnumCréer un type Enum pour limiter les valeurs sélectionnables.
model_name.valueObtenir la valeur réelle du membre de l'énumération (par ex."alexnet"）

Visitezhttp://127.0.0.1:8000/models/alexnet, renvoie :

{"model_name": "alexnet", "message": "Deep Learning FTW!"}

Si une valeur non prédéfinie est passée (par ex./models/foobar), FastAPI renverra une erreur de validation, indiquant que les valeurs autorisées sontalexnet、resnet、lenet。

Paramètres de chemin contenant un chemin

Lorsque vous avez besoin que le paramètre de chemin contienne lui-même un chemin (comme un chemin de fichier), utilisez le convertisseur de chemin de Starlette :

Exemple

from fastapi import FastAPI

app = FastAPI()

# :path indique que ce paramètre peut correspondre à des chemins contenant des barres obliques
@app.get("/files/{file_path:path}")
async def read_file(file_path: str):
    return {"file_path": file_path}

Visitezhttp://127.0.0.1:8000/files/home/johndoe/myfile.txt, renvoie :

{"file_path": "home/johndoe/myfile.txt"}

Remarquez dans l'URL/files/et/home/des doubles barres obliques apparaîtront entre//Ceci est normal, car les paramètres de chemin commencent par/début.

Résumé

Grâce aux déclarations de type standard de Python, les paramètres de chemin de FastAPI peuvent simultanément obtenir :

  • Conversion de données: La chaîne dans l'URL est automatiquement convertie au type déclaré
  • Vérification des données: Lorsque le type ne correspond pas, des informations d'erreur claires sont renvoyées
  • Documentation automatique: Les types et contraintes des paramètres de chemin apparaissent automatiquement dans la documentation de l'API
  • Prise en charge de l'éditeur: Les annotations de type fournissent l'autocomplétion dans l'éditeur
autres extensions