FastAPI-Pfadparameter

Pfadparameter sind die dynamischen Teile des URL-Pfads; dabei werden geschweifte Klammern verwendet, um{}zu deklarieren. FastAPI übergibt Pfadparameter automatisch an die Pfadoperationsfunktion und führt Datenkonvertierung und Validierung basierend auf Typannotationen durch.

Grundlegende Verwendung

Verwenden Sie die Python-Syntax für formatierte Zeichenfolgen, um Pfadparameter zu deklarieren:

Beispiel

from fastapi import FastAPI

app = FastAPI()

# {item_id} ist ein Pfadparameter
@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

Besuchen Siehttp://127.0.0.1:8000/items/5, gibt zurück:

{"item_id": 5}

Beachten Sie: Das Zurückgegebeneitem_idist eine Ganzzahl5, keine Zeichenfolge"5". FastAPI, unter Verwendung von Typannotationen,item_id: intkonvertiert automatisch die Zeichenfolge in der URL in eine Ganzzahl.

Datenkonvertierung

Wenn Sie den Typ alsintWenn , führt FastAPI automatisch eine Typkonvertierung durch:

# 传入整数，正常工作
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

Besuchen Siehttp://127.0.0.1:8000/items/fooWenn , die von FastAPI zurückgegebene Validierungsfehlerinformation:

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

Die Validierungsfehlermeldungen von FastAPI sind sehr klar und geben die genaue Fehlerstelle an (loc), Fehlertyp (type) und Fehlerbeschreibung (msg). Dies ist beim Debuggen sehr nützlich.

Der Typ des Pfadparameters

exceptint, können Sie auch andere Standard-Python-Typen verwenden:

TypeBeschreibungURL-Beispiel
strString (Standardtyp)/items/foo
intInteger/items/5
floatGleitkommazahl/items/5.5
boolBoolescher Wert/items/true
uuid.UUIDUUID/items/3fa85f64-5717-4562-b3fc-2c963f66afa6

Die Reihenfolge der Pfade ist wichtig

Wenn mehrere Routen dieselbe URL abgleichen können, bestimmt die Reihenfolge der Definition das Übereinstimmungsergebnis. FastAPI gleicht Routen nacheinander in der Reihenfolge ab, in der sie definiert sind, und die erste übereinstimmende Route wird ausgeführt.

Beispiel

from fastapi import FastAPI

app = FastAPI()

# Muss vor /users/{user_id} definiert werden
@app.get("/users/me")
async def read_user_me():
    """Aktuelle Benutzerinformationen abrufen"""
    return {"user_id": "der aktuelle Benutzer"}


@app.get("/users/{user_id}")
async def read_user(user_id: str):
    """Benutzerinformationen nach ID abrufen"""
    return {"user_id": user_id}

wenn du ... platzierst/users/mePlatzieren/users/{user_id}Danach dann zugreifen/users/meFastAPI wird berücksichtigen"me"Jauser_idden Wert, wodurch die falsche Funktion zugeordnet wird.

Routen mit festen Pfaden müssen vor Routen mit dynamischen Pfadparametern platziert werden, andernfalls „verschlucken“ die dynamischen Parameter den Wert des festen Pfads.

Pfadparameter mit vorgegebenen Werten (Enum)

Wenn Sie einen Pfadparameter auf mehrere feste Werte beschränken müssen, können Sie PythonsEnumTyp:

Beispiel

from enum import Enum
from fastapi import FastAPI


# Erstelle eine Enum-Klasse, die von str und Enum erbt
class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"


app = FastAPI()


@app.get("/models/{model_name}")
async def get_model(model_name: ModelName):
    # Kann mit Enum-Mitgliedern verglichen werden
    if model_name is ModelName.alexnet:
        return {"model_name": model_name, "message": "Deep Learning FTW!"}

    if model_name.value == "lenet":
        return {"model_name": model_name, "message": "LeCNN alle Bilder"}

    return {"model_name": model_name, "message": "Hab ein paar Residuen"}

Kernpunkte der Enum-Klassen:

KernpunkteBeschreibung
Vererbungstrdamit die API-Dokumentation den Werttyp als String erkennt und eine korrekte Darstellung sicherstellt
VererbungEnumErstelle einen Enum-Typ, um die auswählbaren Werte einzuschränken.
model_name.valueHole den tatsächlichen Wert des Enum-Mitglieds (z. B."alexnet"）

Besuchen Siehttp://127.0.0.1:8000/models/alexnet, gibt zurück:

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

Wenn ein Nicht-Preset-Wert übergeben wird (z. B./models/foobar), gibt FastAPI einen Validierungsfehler zurück, der angibt, dass die erlaubten Werte sindalexnet、resnet、lenet。

Pfadparameter, die einen Pfad enthalten

Wenn der Pfadparameter selbst einen Pfad enthalten soll (z. B. einen Dateipfad), verwenden Sie den Pfadkonverter von Starlette:

Beispiel

from fastapi import FastAPI

app = FastAPI()

# :path gibt an, dass dieser Parameter Pfade mit Schrägstrichen abgleichen kann
@app.get("/files/{file_path:path}")
async def read_file(file_path: str):
    return {"file_path": file_path}

Besuchen Siehttp://127.0.0.1:8000/files/home/johndoe/myfile.txt, gibt zurück:

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

Beachten Sie in der URL/files/und/home/doppelte Schrägstriche erscheinen zwischen//Das ist normal, denn Pfadparameter beginnen mit/Anfang.

Zusammenfassung

Durch Python-Standard-Typdeklarationen können FastAPI-Pfadparameter gleichzeitig Folgendes erhalten:

  • Datenkonvertierung: Die Zeichenfolge in der URL wird automatisch in den deklarierten Typ konvertiert
  • Datenüberprüfung: Wenn der Typ nicht übereinstimmt, werden klare Fehlerinformationen zurückgegeben
  • Automatische Dokumentation: Die Typen und Einschränkungen von Pfadparametern erscheinen automatisch in der API-Dokumentation
  • Editor-Unterstützung: Typannotationen bieten Autovervollständigung im Editor
Weitere Erweiterungen