FastAPI Response-Modell

Response-Modelle werden verwendet, um die von der API zurückgegebene Datenstruktur zu deklarieren. Durch die Deklaration eines Response-Modells übernimmt FastAPI automatisch die Validierung, Serialisierung und Filterung der Ausgabedaten, sodass der Client nur die erwarteten Daten erhält.


Verwendung von Rückgabetyp-Annotationen

Der einfachste Weg ist, den Rückgabetyp der Pfadoperation-Funktion direkt zu annotieren:

Beispiel

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float


@app.get("/items/{item_id}", response_model=Item)
async def read_item(item_id: int):
    # Die zurückgegebenen Daten werden automatisch gemäß dem Item-Modell gefiltert und validiert
    return {
        "name": "Foo",
        "description": "Ein sehr schönes Item",
        "price": 22.2,
        "secret": "Dies sollte nicht sichtbar sein"⟧# Felder, die nicht in Item sind, werden ausgeschlossen,  # Fields not in Item will be filtered
    }

FastAPI verwendet das Response-Modell, um Folgendes zu erreichen:

FunktionenBeschreibung
DatenüberprüfungWenn die zurückgegebenen Daten nicht mit dem Modell übereinstimmen, deutet dies auf ein Problem mit dem Anwendungscode hin.
DatenfilterungNur die im Modell definierten Felder zurückgeben, zusätzliche Felder herausfiltern (dies ist wichtig für die Sicherheit).
Dokumentation generierenDie Antwortstruktur in der OpenAPI-Dokumentation anzeigen.
SerialisierungPydantic (Rust-Implementierung) verwenden, um Daten effizient in JSON umzuwandeln.

response_model-Parameter

Wenn der Rückgabetyp nicht mit dem Response-Modell übereinstimmt, verwenden Sie den Parameter des Decoratorsresponse_modelParameter:

Beispiel

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

app = FastAPI()


# Eingabemodell (enthält Passwort)
class UserIn(BaseModel):
    username: str
    password: str
    email: EmailStr


# Ausgabemodell (ohne Passwort)
class UserOut(BaseModel):
    username: str
    email: EmailStr


# Funktion empfängt UserIn, aber die Antwort verwendet UserOut
@app.post("/users/", response_model=UserOut)
async def create_user(user: UserIn):
    # Der zurückgegebene Benutzer enthält das Passwort, aber response_model=UserOut filtert das Passwort heraus.
    return user

Dies ist eine wichtige Möglichkeit, sensible Daten zu schützen. Durch die Verwendung unterschiedlicher Eingabe- und Ausgabemodelle erscheinen sensible Felder wie Passwörter niemals in API-Antworten.


Rückgabetyp und Datenfilterung

Empfohlene Klassenvererbung zur Umsetzung der Trennung von Eingabe-/Ausgabemodell; dieses Beispiel ermöglicht es sowohl Editor und mypy, die Typen korrekt zu verstehen, als auch FastAPI, Daten zu filtern:

Beispiel

from fastapi import FastAPI
from pydantic import BaseModel, EmailStr

app = FastAPI()


# Basis-Benutzermodell
class BaseUser(BaseModel):
    username: str
    email: EmailStr


# Eingabemodell: erbt vom Basismodell, fügt ein Passwortfeld hinzu
class UserIn(BaseUser):
    password: str


@app.post("/users/")
async def create_user(user: UserIn) -> BaseUser:
    # Die Rückgabetyp-Annotation ist BaseUser, und FastAPI wird das Passwortfeld herausfiltern.
    # Der Editor und mypy sind ebenfalls zufrieden, weil UserIn eine Unterklasse von BaseUser ist
    return user

Nicht gesetzte Standardwerte ausschließen

Nutzungresponse_model_exclude_unset=True, nur Felder zurückgeben, für die tatsächlich Werte gesetzt sind:

Beispiel

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float = 10.5
    tags: list[str] = []


items = {
    "foo": {"name": "Foo", "price": 50.2},
    "bar": {"name": "Bar", "description": "Die Barkeeper", "price": 62, "tax": 20.2},
    "baz": {"name": "Baz", "description": None, "price": 50.2, "tax": 10.5, "tags": []},
}


@app.get("/items/{item_id}", response_model=Item, response_model_exclude_unset=True)
async def read_item(item_id: str):
    return items[item_id]

Vergleich der Antworten für verschiedene item_id:

item_idresponseBeschreibung
foo{"name": "Foo", "price": 50.2}Nur explizit gesetzte Felder werden zurückgegeben, Standardwerte werden weggelassen.
bar{"name": "Bar", "description": "...", "price": 62, "tax": 20.2}Alle Felder haben tatsächliche Werte, daher werden alle zurückgegeben

Zugehörige Filterparameter:

ParameterBeschreibung
response_model_exclude_unsetFelder mit nicht gesetzten Werten ausschließen
response_model_exclude_defaultsFelder mit Standardwerten ausschließen
response_model_exclude_noneFelder mit dem Wert None ausschließen

Bestimmte Felder ein-/ausschließen

Nutzungresponse_model_includeundresponse_model_excludeAusgabefelder präzise steuern:

Beispiel

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float = 10.5


# Enthält nur name und description
@app.get("/items/{item_id}", response_model=Item, response_model_include={"name", "description"})
async def read_item_name(item_id: str):
    return items[item_id]


# Tax ausschließen
@app.get("/items/{item_id}/no-tax", response_model=Item, response_model_exclude={"tax"})
async def read_item_no_tax(item_id: str):
    return items[item_id]

Obwohlresponse_model_includeundresponse_model_excludeKann Felder schnell filtern, aber es wird empfohlen, stattdessen mehrere Modellklassen zu verwenden, da sich die ausgeschlossenen Felder nicht aus der OpenAPI-Dokumentation entfernen lassen.


Zusammenfassung

  • Nutzungresponse_modelParameter- oder Rückgabetyp-Annotationen deklarieren das Antwortmodell.
  • Die Kernrolle des Antwortmodells ist die Datenfilterung, die sensible Daten davor schützt, preisgegeben zu werden.
  • Verwenden Sie unterschiedliche Modelle für Eingabe und Ausgabe, um sicherzustellen, dass Felder wie Passwörter nicht in der Antwort erscheinen.
  • response_model_exclude_unsetNur tatsächlich gesetzte Felder zurückgeben
  • Es wird empfohlen, Modellvererbung + Rückgabetyp-Annotationen zu verwenden anstelle vonresponse_model_include/exclude
Weitere Erweiterungen