FastAPI-Pydantic-Modell
Pydantic ist eine Kernabhängigkeit von FastAPI und wird für Datenvalidierung und Serialisierung verwendet. Es ermöglicht Ihnen, Datenmodelle mithilfe von standardmäßigen Python-Typannotationen zu definieren, und übernimmt automatisch Datenvalidierung, Typkonvertierung und Dokumentationserstellung.
Was ist Pydantic
Pydantic ist eine Python-Bibliothek zur Datenvalidierung. Ihre Kernphilosophie lautet:Definieren Sie Datenstrukturen mit Python-Typannotationen, und Pydantic übernimmt automatisch Validierung und KonvertierungIn FastAPI wird Pydantic hauptsächlich verwendet für:
| Zweck | Beschreibung |
|---|---|
| Validierung des Anfragekörpers | Automatisch validieren, ob die von Clients gesendeten JSON-Daten der Modelldefinition entsprechen |
| Serialisierung des Antwortkörpers | Modelldaten automatisch in JSON-Antworten konvertieren |
| Automatische Dokumentation | Modellfelder, Typen und Validierungsregeln erscheinen automatisch in der API-Dokumentation |
| Editor-Unterstützung | Modellattribute erhalten vollständige Autovervollständigung im Editor |
Pydantic-Modelle definieren
Eine Vererbung erstellenBaseModelKlassen, die Felder mit standardmäßigen Python-Typen deklarieren:
Beispiel
class Item(BaseModel):
name: str # Erforderlich: Produktname
description: str | None = None # Optional: Produktbeschreibung
price: float # Erforderlich: Produktpreis
tax: float | None = None # Optional: Steuer
Ob ein Feld erforderlich ist, hängt davon ab, ob es einen Standardwert hat:
| Fields | Deklarationsmethode | Erforderlich? |
|---|---|---|
name | name: str | Erforderlich |
description | description: str | None = None | Optional |
price | price: float | Erforderlich |
tax | tax: float | None = None | Optional |
Pydantic-Modelle verwenden
Als Request-Body
Die häufigste Verwendung ist, ein Modell als Parameter einer Pfadoperation-Funktion zu deklarieren:
Beispiel
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
@app.post("/items/")
async def create_item(item: Item):
# FastAPI validiert den Request-Body automatisch und weist ihn nach erfolgreicher Validierung dem Parameter item zu
return item
Auf Modelldaten zugreifen und sie bearbeiten
Beispiel
async def create_item(item: Item):
# Auf Modellattribute zugreifen
print(item.name) # Direkt auf Attribute zugreifen
print(item.price) # Editor bietet Autovervollständigung
# In ein Dictionary serialisieren
item_dict = item.model_dump()
print(item_dict) # {"name": "Foo", "description": None, "price": 45.2, "tax": None}
# In einen JSON-String serialisieren
item_json = item.model_dump_json()
print(item_json) # '{"name":"Foo","description":null,"price":45.2,"tax":null}'
return item_dict
Verwendung von Pydantic v2
model_dump()undmodel_dump_json()Ersetzt die v1-dict()undjson()Methode. Die neue Methode hat eine bessere Performance (unter der Haube in Rust implementiert).
Beispiel für Modellvalidierung
Wenn vom Client gesendete Daten nicht der Modelldefinition entsprechen, gibt FastAPI detaillierte Validierungsfehler zurück:
Beispiel
POST /items/
{
"description": "Name und Preis fehlen"
}
# FastAPI-Fehler bei der Antwortvalidierung
{
"detail": [
{
"type": "missing",
"loc": ["body", "name"],
"msg": "Feld erforderlich",
"input": {"description": "Name und Preis fehlen"}
},
{
"type": "missing",
"loc": ["body", "price"],
"msg": "Feld erforderlich",
"input": {"description": "Name und Preis fehlen"}
}
]
}
Wenn falsch typisierte Daten gesendet werden:
// price 应该是数字,但传了字符串
{
"name": "Foo",
"price": "not a number"
}
// FastAPI 返回的错误
{
"detail": [
{
"type": "float_parsing",
"loc": ["body", "price"],
"msg": "Input should be a valid number, unable to parse string as a number",
"input": "not a number"
}
]
}
Häufige Pydantic-v2-Methoden
| Methoden | v2 (Empfohlen) | v1 (veraltet) | Beschreibung |
|---|---|---|---|
| In Dictionary serialisieren | item.model_dump() | item.dict() | Ein Modell in ein Python-Dictionary umwandeln |
| In JSON serialisieren | item.model_dump_json() | item.json() | Modell in JSON-String umwandeln |
| Aus Dictionary erstellen | Item.model_validate(data) | Item.parse_obj(data) | Ein Modell aus einem Dictionary erstellen und validieren |
| Aus JSON erstellen | Item.model_validate_json(json_str) | Item.parse_raw(json_str) | Ein Modell aus einem JSON-String erstellen |
| JSON-Schema abrufen | Item.model_json_schema() | Item.schema() | Abrufen des JSON-Schemas des Modells |
Modellkonfiguration (model_config)
Verwendung von Pydantic v2model_configErsetzt die v1-ConfigInnere Klasse:
Beispiel
class Item(BaseModel):
name: str
price: float
# Pydantic v2 Konfigurationsmethode
model_config = ConfigDict(
json_schema_extra={ # Beispiele in der API-Dokumentation anzeigen
"examples": [
{
"name": "Foo",
"price": 35.4
}
]
}
)
In Pydantic v2,
orm_mode = Truegeändert zufrom_attributes = True,schema_extrageändert zujson_schema_extra,allow_population_by_field_namegeändert zupopulate_by_name。
Modellvererbung
Pydantic-Modelle unterstützen Vererbung, wodurch sich Eingabemodelle und Ausgabemodelle einfach erstellen lassen:
Beispiel
# Basismodell
class UserBase(BaseModel):
username: str # Erforderlich
email: EmailStr # Erforderlich, validiert automatisch das E-Mail-Format
full_name: str | None = None # Optional
# Eingabemodell zum Erstellen eines Benutzers (einschließlich Passwort)
class UserCreate(UserBase):
password: str # Erforderlich
# Ausgabemodell für die Rückgabe von Benutzerinformationen (enthält kein Passwort)
class UserOut(UserBase):
id: int # Vom Server generiert
# Verwendungsbeispiel
@app.post("/users/", response_model=UserOut)
async def create_user(user: UserCreate):
# Funktion empfängt UserCreate (mit Passwort), aber die Antwort verwendet UserOut (ohne Passwort)
# Auf diese Weise erscheint das Passwort nicht in der API-Antwort.
return {"id": 1, **user.model_dump(exclude={"password"})}
Die Verwendung unterschiedlicher Eingabe- und Ausgabemodelle ist ein wichtiges Mittel zum Schutz sensibler Daten. Geben Sie niemals sensible Felder wie Passwörter in API-Antworten zurück.
Zusammenfassung
Wichtige Punkte der Pydantic-Modelle:
- Nutzung
BaseModelDatenmodelle mit Standard-Python-Typen durch Deklarieren von Feldern definieren - Felder mit Standardwerten sind optional, Felder ohne Standardwerte sind erforderlich
- Verwendung von v2
model_dump()、model_validate()und weitere neue Methoden - Erstellen Sie unterschiedliche Eingabe-/Ausgabemodelle durch Modellvererbung, um sensible Daten zu schützen
- Die gesamte Validierung und Dokumentation erfolgt automatisch – deklarieren Sie die Typen nur einmal