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 typing import Annotated
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:

TeilBeschreibung
Annotated[str | None, ...]Typannotationen, BedeutungqKann eine Zeichenkette oder None sein
Query(max_length=50)Validierungsregeln,qDie maximale Länge beträgt 50 Zeichen
= NoneStandardwert, wodurch der Parameter optional wird

FastAPI empfiehlt die Verwendung vonAnnotatedValidierung 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 typing import Annotated
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:

ParameterTypeBeschreibung
min_lengthintMindestlänge
max_lengthintMaximallänge
patternstrÜbereinstimmung mit regulärem Ausdruck

Regulärer Ausdruck^fixedquery$Bedeutung:

  • ^-- Muss mit den folgenden Zeichen beginnen
  • fixedquery-- 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 typing import Annotated
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 typing import Annotated
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 typing import Annotated
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 typing import Annotated
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 alslistAbfrageparameter 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 typing import Annotated
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:

ParameterBeschreibungAnwendungsfall
aliasAlias für den Parameternamen in der URLParametername enthält Bindestrich (z. B.item-query), wenn er kein gültiger Python-Variablenname ist
titleParametertitelParametertitel in der Dokumentation anzeigen
descriptionParameterbeschreibungDetaillierte Beschreibung des Parameters in der Dokumentation anzeigen
deprecatedAls veraltet markiertDer Parameter kann weiterhin verwendet werden, aber er wird in der Dokumentation als "veraltet" gekennzeichnet.
include_in_schemaOb in der API-Dokumentation erscheinen sollFestgelegt alsFalseAusblendbare Parameter

Parameter von OpenAPI ausschließen

Wenn ein Query-Parameter nicht in der API-Dokumentation erscheinen soll:

Beispiel

from typing import Annotated
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:

  • NutzungAnnotated + 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
  • Nutzunglist[str]Mehrere Query-Parameter mit demselben Namen empfangen
Weitere Erweiterungen