FastAPI-Fehlerbehandlung

In der API-Entwicklung ist es notwendig, Fehlerinformationen an den Client zurückzugeben. FastAPI bietetHTTPExceptionum HTTP-Fehler auszulösen, und unterstützt außerdem benutzerdefinierte Exception-Handler, um komplexere Fehlerszenarien zu behandeln.


HTTPException verwenden

Wenn Sie eine Fehlerantwort zurückgeben müssen, lösen Sie eine Ausnahme ausHTTPException:

Beispiel

from fastapi import Fast, HTTPException

app = FastAPI()

items = {"foo": "The Foo Wrestlers", "bar": "The Bar Fighters"}


@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id not in items:
        # Wenn die Ressource nicht existiert, einen 404-Fehler auslösen
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item": items[item_id]}

Besuchen Siehttp://127.0.0.1:8000/items/42Beim Aufruf erhalten Sie:

{
    "detail": "Item not found"
}

Der HTTP-Statuscode ist404。

Beachten Sie, dass hier Folgendes verwendet wirdraiseanstelle vonreturn。HTTPExceptionist eine Ausnahme. Nachdem sie ausgelöst wurde, fängt FastAPI sie ab und gibt die entsprechende HTTP-Fehlerantwort zurück. Dies stimmt mit Pythons Ausnahmebehandlungsmechanismus überein.


HTTPException-Parameter

ParameterTypeBeschreibung
status_codeintHTTP-Statuscode (erforderlich)
detailAnyFehlerdetails können eine Zeichenkette, ein Dictionary, eine Liste usw. sein.
headersdict | NoneZusätzliche Antwort-Header (optional)

Benutzerdefinierte Fehlerdetails

detailDer Parameter kann von beliebigem Typ sein, nicht auf Zeichenketten beschränkt:

Beispiel

from fastapi import Fast, HTTPException

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id == "invalid":
        # detail kann ein dict sein, das weitere Fehlerinformationen enthält
        raise HTTPException(
            status_code=400,
            detail={
                "error_code": "INVALID_ID",
                "message": "Das Format der Produkt-ID ist falsch",
                "hint": "Bitte verwenden Sie eine alphanumerische ID"
            }
        )
    return {"item_id": item_id}

Benutzerdefinierte Antwort-Header hinzufügen

In einigen Szenarien müssen Sie der Fehlerantwort benutzerdefinierte Antwort-Header hinzufügen:

Beispiel

from fastapi import Fast, HTTPException

app = FastAPI()


@app.get("/items-header/{item_id}")
async def read_item_header(item_id: str):
    if item_id == "invalid":
        raise HTTPException(
            status_code=404,
            detail="Item not found",
            headers={"X-Error": "There goes my error"},  # Benutzerdefinierte Antwort-Header
        )
    return {"item": item_id}

In Szenarien, in denen Sie die Anfragefrequenz von Clients begrenzen müssen (Rate Limiting), können Sie den Fehlerantwort-HeadernRetry-Aftereinen Header hinzufügen, der dem Client mitteilt, wann er es erneut versuchen kann.


Benutzerdefinierter Exception-Handler

Sie können Handler für benutzerdefinierte Exceptions oder integrierte Exceptions registrieren, um das Format der Fehlerantwort einheitlich zu behandeln:

Beispiel

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse


# Benutzerdefinierte Exception-Klasse
class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name


app = FastAPI()


# Exception-Handler registrieren
@app.exception_handler(UnicornException)
async def unicorn_exception_handler(request: Request, exc: UnicornException):
    # Eine Fehlerantwort mit benutzerdefiniertem Format zurückgeben
    return JSONResponse(
        status_code=418,
        content={"message": f"Hoppla! {exc.name} hat etwas falsch gemacht"},
    )


@app.get("/unicorns/{name}")
async def read_unicorn(name: str):
    if name == "yolo":
        # Benutzerdefinierte Ausnahme auslösen
        raise UnicornException(name=name)
    return {"unicorn_name": name}

Standard-Exception-Handler überschreiben

FastAPI verfügt über standardmäßige Exception-Handler. Du kannst sie überschreiben, um das Format der Fehlerantwort anzupassen:

Beispiel

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
from starlette.exceptions import HTTPException as StarletteHTTPException

app = FastAPI()


# HTTP-Exception-Handler überschreiben
@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request: Request, exc: StarletteHTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={"error": f"HTTP-Fehler: {exc.detail}"},
    )


# Exception-Handler für die Request-Validierung überschreiben
@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={"error": "Datenvalidierung fehlgeschlagen", "details": exc.errors()},
    )

RequestValidationErrorist eine Exception, die von FastAPI ausgelöst wird, wenn die Validierung der Anfragedaten fehlschlägt. Das Überschreiben ihres Handlers ermöglicht die Anpassung des Antwortformats für Validierungsfehler.


Redirect

NutzungRedirectResponseWeiterleitung implementieren:

Beispiel

from fastapi import FastAPI
from fastapi.responses import RedirectResponse

app = FastAPI()


@app.get("/items/")
async def read_items():
    return {"items": ["foo", "bar"]}


@app.get("/redirect")
async def redirect():
    Weiterleitung zu /items/
    return RedirectResponse(url="/items/")

Benutzerdefinierte Antwort-Header und Statuscode

NutzungJSONResponseBenutzerdefinierte Antwort-Header und Statuscode:

Beispiel

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    content = {"item_id": item_id}
    headers = {"X-Custom-Header": "custom-header-value"}
    return JSONResponse(content=content, headers=headers)

Zusammenfassung

  • Nutzungraise HTTPExceptionEine HTTP-Fehlerantwort zurückgeben
  • detailDer Parameter kann einen beliebigen Typ haben (String, Dictionary, Liste usw.)
  • Nutzung@app.exception_handlerBenutzerdefinierten Exception-Handler registrieren
  • Du kannst die Standard-Exception-Handler von FastAPI überschreiben, um das Fehlerformat zu vereinheitlichen.
  • NutzungRedirectResponseWeiterleitung implementieren
Weitere Erweiterungen