FastAPI Query-Parameter-Validierung
FastAPI ermöglicht es Ihnen, zusätzliche Validierungsregeln und Metadaten für Query-Parameter zu deklarieren, wie z. B. Längenbeschränkungen für Zeichenketten, Regex-Matching usw. ÜberQueryundAnnotated, können Sie die Parametervalidierung verbessern, ohne die Funktionslogik zu ändern.
Grundlegende Validierung
Das folgende Beispiel zeigt Query-Parameter.qMaximale Längenbeschränkung hinzufügen:
Beispiel
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
# Annotated + Query verwenden, um Validierung hinzuzufügen
q: Annotated[str | None, Query(max_length=50)] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Code-Erklärung:
| Teil | Beschreibung |
|---|---|
Annotated[str | None, ...] | Typannotationen, BedeutungqKann eine Zeichenkette oder None sein |
Query(max_length=50) | Validierungsregeln,qDie maximale Länge beträgt 50 Zeichen |
= None | Standardwert, wodurch der Parameter optional wird |
FastAPI empfiehlt die Verwendung von
AnnotatedValidierung auf eine Weise deklarieren, anstattQueryals Standardwert zu verwenden. DennAnnotatedBei diesem Ansatz ist der Standardwert der Funktion der tatsächliche Standardwert, was in Python intuitiver ist und von Editoren und Typprüfungswerkzeugen besser unterstützt wird.
Weitere Validierung hinzufügen
Sie können mehrere Validierungsregeln gleichzeitig hinzufügen:
Beispiel
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
# Außerdem Mindestlänge, maximale Länge und regulären Ausdruck begrenzen
q: Annotated[str | None, Query(min_length=3, max_length=50, pattern="^fixedquery$")] = None,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Validierungsparameter für Zeichenketten:
| Parameter | Type | Beschreibung |
|---|---|---|
min_length | int | Mindestlänge |
max_length | int | Maximallänge |
pattern | str | Übereinstimmung mit regulärem Ausdruck |
Regulärer Ausdruck^fixedquery$Bedeutung:
^-- Muss mit den folgenden Zeichen beginnenfixedquery-- Wert muss exakt gleich seinfixedquery$-- Hier enden; es dürfen keine weiteren Zeichen folgen.
Validierung mit Standardwerten
Sie können sowohl einen Standardwert als auch Validierungsregeln für einen Query-Parameter festlegen:
Beispiel
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
# Der Standardwert ist "fixedquery", und die Mindestlänge beträgt 3
q: Annotated[str, Query(min_length=3)] = "fixedquery",
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Standardwert eines beliebigen Typs (einschließlich Nicht-
NoneWert) macht den Parameter optional. Ohne einen Standardwert und ohneQuery(default=...)Parameter sind erforderlich.
Erforderlicher Parameter
NutzungQuery, wenn du keinen Standardwert deklarierst, ist der Parameter erforderlich:
Beispiel
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
# Kein Wert = None, also ist q ein erforderlicher Parameter.
q: Annotated[str, Query(min_length=3)],
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
results.update({"q": q})
return results
Erforderlich, kann aber None sein
Manchmal benötigst du, dass der Client einen Wert übergibt, aber der Wert kannNone:
Beispiel
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
# Der Client muss den Parameter q angeben, aber der Wert kann None sein
q: Annotated[str | None, Query(min_length=3)],
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Query-Parameter-Liste / mehrere Werte
NutzungQueryDu kannst Query-Parameter deklarieren, die mehrere Werte empfangen:
Beispiel
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
# q kann mehrfach in der URL vorkommen, und die Werte werden als Liste gesammelt
q: Annotated[list[str] | None, Query()] = Keine,
):
query_items = {"q": q}
return query_items
Besuchen Siehttp://127.0.0.1:8000/items/?q=foo&q=bar, gibt zurück:
{"q": ["foo", "bar"]}
Um den Typ als
listAbfrageparameter zu deklarieren, muss explizit verwendet werdenQuery(), andernfalls interpretiert FastAPI ihn als Request-Body.
Metadaten deklarieren
QueryEs unterstützt außerdem das Hinzufügen von Metadaten zu Parametern; diese Informationen werden in der API-Dokumentation angezeigt:
Beispiel
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Annotated[str | None, Query(
title="query string", # Parametertitel
description="Query-String zum Filtern von Produkten", # Parameterbeschreibung
min_length=3,
max_length=50,
alias="item-query", # Alias für den Parameternamen in der URL
deprecated=True, # Als veraltet markieren
)] = Keine,
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
Metadaten-Parameterbeschreibung:
| Parameter | Beschreibung | Anwendungsfall |
|---|---|---|
alias | Alias für den Parameternamen in der URL | Parametername enthält Bindestrich (z. B.item-query), wenn er kein gültiger Python-Variablenname ist |
title | Parametertitel | Parametertitel in der Dokumentation anzeigen |
description | Parameterbeschreibung | Detaillierte Beschreibung des Parameters in der Dokumentation anzeigen |
deprecated | Als veraltet markiert | Der Parameter kann weiterhin verwendet werden, aber er wird in der Dokumentation als "veraltet" gekennzeichnet. |
include_in_schema | Ob in der API-Dokumentation erscheinen soll | Festgelegt alsFalseAusblendbare Parameter |
Parameter von OpenAPI ausschließen
Wenn ein Query-Parameter nicht in der API-Dokumentation erscheinen soll:
Beispiel
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items/")
async def read_items(
# hidden_query wird nicht in der API-Dokumentation erscheinen, kann aber weiterhin verwendet werden
hidden_query: Annotated[str | None, Query(include_in_schema=False)] = Keine,
):
if hidden_query:
return {"hidden_query": hidden_query}
return {"items": [{"item_id": "Foo"}]}
Zusammenfassung
Wichtige Punkte zur Validierung von Query-Parametern:
- Nutzung
Annotated+QueryValidierungsregeln deklarieren (empfohlener Ansatz) - String-Validierung:
min_length、max_length、pattern - Kein Standardwert = erforderlicher Parameter; mit Standardwert = optionaler Parameter
aliasWird für Parameternamen in URLs verwendet, die keine gültigen Python-Variablennamen sind.deprecated=TrueVeraltete Parameter markieren- Nutzung
list[str]Mehrere Query-Parameter mit demselben Namen empfangen