FastAPI Request-Body-Felder und verschachtelte Modelle

Innerhalb eines Pydantic-Modells können SieFieldValidierungsregeln und Metadaten für Felder deklarieren, und Sie können auch Modelle verschachteln, um komplexe JSON-Datenstrukturen zu verarbeiten.


Field verwenden, um Feldvalidierung zu deklarieren

Wird in Pfadoperationsfunktionen verwendetQuery、PathDie Art und Weise, Validierung zu deklarieren, ist dieselbe; in Pydantic-Modellen verwenden SieFieldFeldvalidierung deklarieren:

Beispiel

from typing import Annotated
from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str = Field(min_length=1, max_length=100, description="Produktname")  # Erforderlich, 1-100 Zeichen
    description: str | None = Field(default=None, max_length=300, description="Produktbeschreibung")  # Optional
    price: float = Field(gt=0, description="Produktpreis")  # Erforderlich, muss größer als 0 sein
    tax: float | None = Field(default=None, ge=0, description="Steuer")  # Optional, >= 0


@app.post("/items/")
async def create_item(item: Item):
    return item

FieldUnterstützte Validierungsparameter:

ParametertypParameterBeschreibung
String-Validierungmin_lengthMindestlänge
max_lengthMaximallänge
patternÜbereinstimmung mit regulärem Ausdruck
Numerische Validierunggtgrößer als
gegrößer als oder gleich
ltkleiner als
lekleiner als oder gleich
metadatatitleFeldtitel
descriptionFeldbeschreibung

HinweisFieldfrompydanticImport, statt fromfastapiImport. Dies istQuery、Pathusw. fromfastapiImport unterscheidet sich.


Feld vom Typ Liste

Sie können ein Feld als Liste deklarieren und den Elementtyp angeben:

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
    tags: list[str] = []  # String-Liste, standardmäßig leere Liste


@app.post("/items/")
async def create_item(item: Item):
    return item

Beispiel für den Request-Body:

{
    "name": "Foo",
    "price": 42.0,
    "tags": ["rock", "metal", "bar"]
}

Verwenden Sie Set, um Duplikate zu entfernen

Wenn Tags nicht dupliziert werden sollen, verwenden SiesetTyp:

Beispiel

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()  # Doppelte Tags automatisch entfernen

Selbst wenn die Anfrage doppelte Tags enthält, werden sie in der Antwort automatisch dedupliziert.


Verschachteltes Modell

Der Feldtyp eines Pydantic-Modells kann ein anderes Pydantic-Modell sein, wobei Verschachtelung bis zu beliebiger Tiefe unterstützt wird:

Beispiel

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


# Untermodell: Image
class Image(BaseModel):
    url: HttpUrl      # Automatisch validieren, ob es sich um eine gültige URL handelt
    name: str


# Hauptmodell: Product, enthält Bild-Untermodell
class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    image: Image | None = None  # Optionale Bildinformationen


@app.post("/items/")
async def create_item(item: Item):
    return item

Entsprechende Request-Body-Struktur:

{
    "name": "Foo",
    "description": "The pretender",
    "price": 42.0,
    "tax": 3.2,
    "tags": ["rock", "metal", "bar"],
    "image": {
        "url": "http://example.com/baz.jpg",
        "name": "The Foo live"
    }
}

Untermodell in einer Liste

Du kannst Untermodelle in eine Liste aufnehmen:

Beispiel

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float
    tax: float | None = None
    tags: set[str] = set()
    images: list[Image] | None = None  # Bildliste


@app.post("/items/")
async def create_item(item: Item):
    return item

Zugehöriger Request-Body:

{
    "name": "Foo",
    "price": 42.0,
    "images": [
        {"url": "http://example.com/baz.jpg", "name": "The Foo live"},
        {"url": "http://example.com/dave.jpg", "name": "The Baz"}
    ]
}

Tief verschachtelte Modelle

Sie können verschachtelte Strukturen beliebiger Tiefe definieren:

Beispiel

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


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


class Offer(BaseModel):
    name: str
    description: str | None = None
    price: float
    items: list[Item]  # Offer enthält mehrere Items, und ein Item enthält mehrere Images


@app.post("/offers/")
async def create_offer(offer: Offer):
    return offer

Reiner Listen-Request-Body

Wenn die äußerste Ebene des Request-Bodys ein JSON-Array ist, können Sie im Funktionsparameter direkt einen Listentyp deklarieren:

Beispiel

from fastapi import FastAPI
from pydantic import BaseModel, HttpUrl

app = FastAPI()


class Image(BaseModel):
    url: HttpUrl
    name: str


# Der Request-Body ist direkt eine Liste von Images
@app.post("/images/multiple/")
async def create_multiple_images(images: list[Image]):
    return images

Request-Body, bestehend aus einem beliebigen dict

Wenn du Wörterbuchdaten mit ungewissen Schlüsselnamen empfangen musst, kannst du deklarierendictRequest-Body vom Typ:

Beispiel

from fastapi import FastAPI

app = FastAPI()


# Empfange ein dict mit int-Schlüsseln und float-Werten
@app.post("/index-weights/")
async def create_index_weights(weights: dict[int, float]):
    return weights

Beispiel für den Request-Body:

{
    "1": 0.5,
    "2": 1.5,
    "3": 2.0
}

JSON unterstützt nur Schlüssel vom Typ String, aber Pydantic konvertiert String-Schlüssel automatisch in den deklarierten Typ (wie z. B. denint)。


Zusammenfassung

  • Mit Pydantic'sFieldValidierung und Metadaten zu Modellfeldern hinzufügen
  • list[str]、set[str]Sammlungstypen wie diese können als list/set-Felder deklariert werden
  • Modelle können verschachtelt werden und unterstützen JSON-Strukturen beliebiger Tiefe
  • HttpUrlund andere spezielle Typen validieren das Format automatisch
  • Einfache Listen und beliebige Dictionaries können ebenfalls als Request-Body-Typen verwendet werden
Weitere Erweiterungen