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:

ZweckBeschreibung
Validierung des AnfragekörpersAutomatisch validieren, ob die von Clients gesendeten JSON-Daten der Modelldefinition entsprechen
Serialisierung des AntwortkörpersModelldaten automatisch in JSON-Antworten konvertieren
Automatische DokumentationModellfelder, Typen und Validierungsregeln erscheinen automatisch in der API-Dokumentation
Editor-UnterstützungModellattribute erhalten vollständige Autovervollständigung im Editor

Pydantic-Modelle definieren

Eine Vererbung erstellenBaseModelKlassen, die Felder mit standardmäßigen Python-Typen deklarieren:

Beispiel

from pydantic import BaseModel


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:

FieldsDeklarationsmethodeErforderlich?
namename: strErforderlich
descriptiondescription: str | None = NoneOptional
priceprice: floatErforderlich
taxtax: float | None = NoneOptional

Pydantic-Modelle verwenden

Als Request-Body

Die häufigste Verwendung ist, ein Modell als Parameter einer Pfadoperation-Funktion zu deklarieren:

Beispiel

from fastapi import FastAPI
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

@app.post("/items/")
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 v2model_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

# Der Client hat Daten ohne erforderliche Felder gesendet
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

Methodenv2 (Empfohlen)v1 (veraltet)Beschreibung
In Dictionary serialisierenitem.model_dump()item.dict()Ein Modell in ein Python-Dictionary umwandeln
In JSON serialisierenitem.model_dump_json()item.json()Modell in JSON-String umwandeln
Aus Dictionary erstellenItem.model_validate(data)Item.parse_obj(data)Ein Modell aus einem Dictionary erstellen und validieren
Aus JSON erstellenItem.model_validate_json(json_str)Item.parse_raw(json_str)Ein Modell aus einem JSON-String erstellen
JSON-Schema abrufenItem.model_json_schema()Item.schema()Abrufen des JSON-Schemas des Modells

Modellkonfiguration (model_config)

Verwendung von Pydantic v2model_configErsetzt die v1-ConfigInnere Klasse:

Beispiel

from pydantic import BaseModel, ConfigDict


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

from pydantic import BaseModel, EmailStr


# 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:

  • NutzungBaseModelDatenmodelle mit Standard-Python-Typen durch Deklarieren von Feldern definieren
  • Felder mit Standardwerten sind optional, Felder ohne Standardwerte sind erforderlich
  • Verwendung von v2model_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
Weitere Erweiterungen