FastAPI-Request-Body

Der Request-Body ist die Datenmenge, die vom Client an die API gesendet wird. Wenn Sie JSON-Daten vom Client empfangen müssen, verwenden Sie den Request-Body, um sie zu übergeben. FastAPI verwendet Pydantic-Modelle, um die Struktur des Request-Bodys zu deklarieren, und führt automatisch Datenvalidierung, Konvertierung und Dokumentationserstellung durch.


Der Unterschied zwischen Request-Body und Abfrageparametern

DatenübertragungsmethodenPositionAnwendbare SzenarienHTTP-Methoden
PfadparameterURL-Pfad/items/5Ressource identifizierenGET, PUT, DELETE usw.
Query-ParameterIn der URL?key=valueOptionale Parameter wie Filterung und PaginierungHauptsächlich GET
Request-BodyDie JSON-Daten der AnfrageÜbermittlung komplexer DatenPOST、PUT、PATCH

Zum Senden von Daten sollte man verwendenPOST(am häufigsten),PUT、DELETEoderPATCHObwohl FastAPI technisch GET-Anfragen mit einem Request-Body unterstützt, entspricht dies nicht den HTTP-Spezifikationen, und die Swagger UI zeigt keine Request-Body-Dokumentation für GET-Anfragen an.


Den Request-Body mit einem Pydantic-Modell deklarieren

BaseModel importieren

from pydantic import BaseModel

2. Datenmodell erstellen

Definieren Sie eine Klasse, die erbtBaseModelDeklarieren Sie für die Klasse alle Attribute mit Python-Standardtypen:

Beispiel

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


# Das Datenmodell für den Request-Body definieren
class Item(BaseModel):
    name: str               # Erforderlich: Produktname
    description: str | None = None  # Optional: Produktbeschreibung
    price: float            # Erforderlich: Produktpreis
    tax: float | None = None        # Optional: Steuer


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

Die Regeln dafür, ob Attribute erforderlich sind, sind dieselben wie für Query-Parameter:

  • Attribute mit Standardwerten sind optional (z. B.,description、tax)
  • Attribute ohne Standardwerte sind erforderlich (z. B.,name、price)

Die folgenden JSON sind alle gültige Request-Bodys:

// 包含所有字段
{
    "name": "Foo",
    "description": "可选描述",
    "price": 45.2,
    "tax": 3.5
}

// 省略可选字段
{
    "name": "Foo",
    "price": 45.2
}

FastAPIs Umgang mit dem Request-Body

Allein durch die Deklaration von Python-Typen kann FastAPI automatisch Folgendes tun:

FunktionenBeschreibung
Request-Body lesenDie Daten aus der Anfrage im JSON-Format lesen
TypumwandlungDie Daten in die deklarierten Typen umwandeln (z. B. string zu float)
DatenüberprüfungDaten validieren und bei Ungültigkeit klare Fehlermeldungen zurückgeben
Parameter zuweisenDie validierten Daten den Funktionsparametern zuweisen, mit Autovervollständigung im Editor
Dokumentation generierenAutomatisch ein JSON-Schema generieren, das in der API-Dokumentation erscheint

Modellattribute verwenden

Innerhalb der Pfadoperationsfunktion können Sie auf alle Attribute des Modells zugreifen, genau wie beim Arbeiten mit einem normalen Python-Objekt:

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):
    # Direkter Zugriff auf Modellattribute
    item_dict = item.model_dump()  # Pydantic v2 Serialisierungsmethode
    if item.tax:
        # Preis inklusive Steuer berechnen
        price_with_tax = item.price + item.tax
        item_dict.update({"price_with_tax": price_with_tax})
    return item_dict

Verwendung von Pydantic v2model_dump()Ersetzt die v1dict()Methode zum Serialisieren von Modelldaten.model_dump()Gibt ein Dictionary zurück, das alle Felder des Modells enthält.


Request-Body + Pfadparameter

Du kannst Pfadparameter und einen Request-Body gleichzeitig deklarieren, und FastAPI holt die Daten automatisch von den richtigen Stellen:

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


# Verwendung von Pfadparametern und Request-Body
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {"item_id": item_id, "item_name": item.name}

FastAPI-Erkennungsregeln:

  • item_idim Pfad{item_id}erscheint in -> Pfadparameter
  • itemDer Typ ist ein Pydantic-Modell -> Request-Body

Request-Body + Pfadparameter + Query-Parameter

Alle drei können gleichzeitig verwendet werden:

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


# Gleichzeitige Verwendung von Pfadparametern, Query-Parametern und Request-Body
@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item, q: str | None = None):
    result = {"item_id": item_id, **item.model_dump()}
    if q:
        result.update({"q": q})
    return result

Die vollständigen Parameter-Erkennungsregeln von FastAPI:

ErkennungsbedingungParameterquelle
Parameternamen im Pfad{}deklariert inPfadparameter
Der Parameter ist ein einzelner Typ (int、str、boolusw.)Query-Parameter
Wenn der Parametertyp ein Pydantic-Modell istRequest-Body

Zusammenfassung

Kernpunkte des Request-Bodys:

  • Mit Pydantic'sBaseModelRequest-Body-Struktur definieren
  • Felder mit Standardwerten sind optional; Felder ohne Standardwerte sind erforderlich.
  • Der Request-Body kann zusammen mit Pfadparametern und Query-Parametern verwendet werden.
  • FastAPI führt automatisch Datenvalidierung, Typkonvertierung und Dokumentationsgenerierung durch.
  • Verwendung von Pydantic v2model_dump()Serialisierung durchführen
Weitere Erweiterungen