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 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:
| Funktionen | Beschreibung |
|---|---|
| Datenüberprüfung | Wenn die zurückgegebenen Daten nicht mit dem Modell übereinstimmen, deutet dies auf ein Problem mit dem Anwendungscode hin. |
| Datenfilterung | Nur die im Modell definierten Felder zurückgeben, zusätzliche Felder herausfiltern (dies ist wichtig für die Sicherheit). |
| Dokumentation generieren | Die Antwortstruktur in der OpenAPI-Dokumentation anzeigen. |
| Serialisierung | Pydantic (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 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 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 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_id | response | Beschreibung |
|---|---|---|
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:
| Parameter | Beschreibung |
|---|---|
response_model_exclude_unset | Felder mit nicht gesetzten Werten ausschließen |
response_model_exclude_defaults | Felder mit Standardwerten ausschließen |
response_model_exclude_none | Felder mit dem Wert None ausschließen |
Bestimmte Felder ein-/ausschließen
Nutzungresponse_model_includeundresponse_model_excludeAusgabefelder präzise steuern:
Beispiel
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]
Obwohl
response_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
- Nutzung
response_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 von
response_model_include/exclude