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übertragungsmethoden | Position | Anwendbare Szenarien | HTTP-Methoden |
|---|---|---|---|
| Pfadparameter | URL-Pfad/items/5 | Ressource identifizieren | GET, PUT, DELETE usw. |
| Query-Parameter | In der URL?key=value | Optionale Parameter wie Filterung und Paginierung | Hauptsächlich GET |
| Request-Body | Die JSON-Daten der Anfrage | Übermittlung komplexer Daten | POST、PUT、PATCH |
Zum Senden von Daten sollte man verwenden
POST(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 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:
| Funktionen | Beschreibung |
|---|---|
| Request-Body lesen | Die Daten aus der Anfrage im JSON-Format lesen |
| Typumwandlung | Die Daten in die deklarierten Typen umwandeln (z. B. string zu float) |
| Datenüberprüfung | Daten validieren und bei Ungültigkeit klare Fehlermeldungen zurückgeben |
| Parameter zuweisen | Die validierten Daten den Funktionsparametern zuweisen, mit Autovervollständigung im Editor |
| Dokumentation generieren | Automatisch 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 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 v2
model_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 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 -> PfadparameteritemDer Typ ist ein Pydantic-Modell -> Request-Body
Request-Body + Pfadparameter + Query-Parameter
Alle drei können gleichzeitig verwendet werden:
Beispiel
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:
| Erkennungsbedingung | Parameterquelle |
|---|---|
Parameternamen im Pfad{}deklariert in | Pfadparameter |
Der Parameter ist ein einzelner Typ (int、str、boolusw.) | Query-Parameter |
| Wenn der Parametertyp ein Pydantic-Modell ist | Request-Body |
Zusammenfassung
Kernpunkte des Request-Bodys:
- Mit Pydantic's
BaseModelRequest-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 v2
model_dump()Serialisierung durchführen