Einstieg
Erste API
FastAPI baut auf Starlette und Pydantic auf. uvicorn ist der ASGI-Server. --reload aktiviert Auto-Reload während der Entwicklung.
# install FastAPI and uvicorn
pip install fastapi uvicorn
# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"Hello": "World"}
# run: uvicorn main:app --reloadMit Uvicorn starten
Die App-Instanz 'main:app' bedeutet Modul 'main', Variable 'app'. --reload nur in der Entwicklung; in Produktion ohne starten und einen Prozess-Manager verwenden.
# development with auto-reload
uvicorn main:app --reload
# specify host and port
uvicorn main:app --host 0.0.0.0 --port 8000
# run programmatically
import uvicorn
if __name__ == "__main__":
uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)Async-Path-Operations
Path operations lassen sich mit 'def' (läuft im Threadpool) oder 'async def' deklarieren. async def verwenden, wenn die Funktion I/O über async-Bibliotheken macht; blockierende Aufrufe in async def blockieren die Event-Loop.
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def read_root():
return {"message": "hello"}
@app.get("/sync")
def read_sync():
return {"message": "sync also works"}
# use async when calling async libs (httpx, databases)
@app.get("/data")
async def fetch_data():
import httpx
async with httpx.AsyncClient() as client:
r = await client.get("https://api.example.com")
return r.json()Path-Operation-Decoratoren
FastAPI unterstützt alle HTTP-Methoden: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD. Jede mappt auf einen Decorator. status_code= auf dem Decorator überschreibt den Standard-Erfolgsstatus.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items")
def list_items(): ...
@app.post("/items")
def create_item(): ...
@app.put("/items/{item_id}")
def replace_item(item_id: int): ...
@app.patch("/items/{item_id}")
def update_item(item_id: int): ...
@app.delete("/items/{item_id}")
def delete_item(item_id: int): ...
@app.options("/items")
def options_items(): ...
@app.head("/items")
def head_items(): ...JSON-Antwort & Status
Ein zurückgegebenes Dict/Liste wird automatisch zu JSON mit 200 konvertiert (oder deinem status_code). Für volle Kontrolle über Status, Header oder Inhalt direkt ein JSONResponse oder Response zurückgeben.
from fastapi import FastAPI, status
from fastapi.responses import JSONResponse
app = FastAPI()
@app.get("/plain")
def plain():
return {"key": "value"} # auto JSON, 200 OK
@app.post("/created", status_code=status.HTTP_201_CREATED)
def created():
return {"id": 1}
@app.get("/custom")
def custom():
return JSONResponse(
status_code=418,
content={"error": "I'm a teapot"},
headers={"X-Custom": "yes"},
)Projektstruktur
Eine wachsende App mit APIRouter in Module aufteilen und über app.include_router() registrieren. Pydantic-Schemas, DB-Setup und Dependencies in eigene Dateien für Wartbarkeit.
myapp/
main.py # creates the FastAPI app
routers/
users.py # APIRouter for /users
items.py # APIRouter for /items
models/
schemas.py # Pydantic models
database.py # DB engine & session
dependencies.py # shared Depends functions
tests/
test_main.py
# main.py
from fastapi import FastAPI
from routers import users, items
app = FastAPI()
app.include_router(users.router)
app.include_router(items.router, prefix="/items")Path-Parameter
Grundlegende Path-Parameter
Werte aus dem Pfad sind Strings, außer man ergänzt eine Typ-Annotation. Der Parametername im Pfad muss exakt dem Funktionsargumentnamen entsprechen.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id):
return {"item_id": item_id}
# GET /items/42 -> {"item_id": "42"} (string by default)Typkonvertierung
Eine Typ-Annotation (int, float, bool, str, Enum) lässt FastAPI den Pfadwert validieren und konvertieren. Ungültige Werte geben eine 422-Antwort mit klarer Fehlermeldung.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id: int):
return {"item_id": item_id}
# GET /items/3 -> {"item_id": 3}
# GET /items/abc -> 422 Validation Error (not an integer)Pfad-Validierung
Path() ergänzt Metadaten und Constraints zu einem Pfadparameter. Numerische Constraints: ge (>=), gt (>), le (<=), lt (<). Pfadparameter sind immer erforderlich, daher kann Path() keinen Default setzen.
from fastapi import FastAPI, Path
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(
item_id: int = Path(
title="The ID of the item",
description="Must be a positive integer",
ge=1,
le=1000,
),
):
return {"item_id": item_id}Numerische Constraints
ge/gt/le/lt auf int- oder float-Pfadparametern erzwingen numerische Bereiche. Kombinierte Constraints geben präzise Grenzwertvalidierung mit automatischen 422-Fehlern.
from fastapi import FastAPI, Path
app = FastAPI()
@app.get("/ratio/{value}")
def ratio(
value: float = Path(gt=0, lt=1), # 0 < value < 1
):
return {"value": value}
@app.get("/page/{page}")
def page(
page: int = Path(ge=1), # >= 1
size: int = Path(le=100), # <= 100
):
return {"page": page, "size": size}Routen-Reihenfolge zählt
Routen werden in Deklarations-Reihenfolge gematcht. Konkrete Pfade wie /users/me vor dynamische Muster wie /users/{user_id} deklarieren, sonst überdeckt die dynamische Route die konkrete.
from fastapi import FastAPI
app = FastAPI()
@app.get("/users/me")
def read_current_user():
return {"user": "me"}
@app.get("/users/{user_id}")
def read_user(user_id: str):
return {"user_id": user_id}
# /users/me MUST be declared before /users/{user_id}
# otherwise 'me' would match the {user_id} patternEnum-Pfadparameter
Ein Enum-Typ für einen Pfadparameter beschränkt ihn auf vordefinierte Werte und erzeugt ein Enum-Schema in den OpenAPI-Docs. (str, Enum) ableiten, damit Werte als Strings serialisieren.
from enum import Enum
from fastapi import FastAPI
class ModelName(str, Enum):
alexnet = "alexnet"
resnet = "resnet"
lenet = "lenet"
app = FastAPI()
@app.get("/models/{model_name}")
def get_model(model_name: ModelName):
if model_name is ModelName.alexnet:
return {"model": model_name, "layers": 5}
return {"model": model_name}
# GET /models/resnet -> {"model": "resnet"}Query-Parameter
Grundlegende Query-Parameter
Funktionsparameter, die NICHT im Pfad sind, werden Query-Parameter. Ein Default macht sie optional; der Default greift, wenn der Query-Key fehlt.
from fastapi import FastAPI
app = FastAPI()
fake_items = [{"item": "a"}, {"item": "b"}, {"item": "c"}]
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10):
return fake_items[skip : skip + limit]
# GET /items?skip=0&limit=2
# GET /items -> skip=0, limit=10Optionale Query-Parameter
Optional[str] = None (oder str | None = None auf Python 3.10+) für einen Query-Parameter, der fehlen darf. Erforderliche Parameter haben schlicht keinen Default-Wert.
from typing import Optional
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id: str, q: Optional[str] = None):
if q:
return {"item_id": item_id, "q": q}
return {"item_id": item_id}
# GET /items/1?q=hello
# GET /items/1 (q is None)Query-Validierung
Query() ergänzt Validierung: min_length/max_length für Strings, ge/gt/le/lt für Zahlen, pattern (Regex) für das String-Format. default= setzt einen Wert und wendet trotzdem Constraints an.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/search")
def search(q: str = Query(min_length=3, max_length=50, pattern="^[a-zA-Z]+$")):
return {"q": q}
@app.get("/page")
def page(limit: int = Query(default=10, ge=1, le=100)):
return {"limit": limit}Boolesche Konvertierung
Bool-Query-Parameter akzeptieren viele truthy Werte: true, 1, yes, on (Groß-/Kleinschreibung egal). Alles andere gilt als false. Ungültige Typen wie ?active=maybe geben 422.
from fastapi import FastAPI
app = FastAPI()
@app.get("/flags")
def flags(active: bool = False):
return {"active": active}
# GET /flags?active=true -> {"active": true}
# GET /flags?active=1 -> {"active": true}
# GET /flags?active=yes -> {"active": true}
# GET /flags?active=off -> {"active": false}Listen-Query-Parameter
Ein List[str]-Parameter akzeptiert denselben Key mehrfach im Query-String. Query(default=[]) für eine leere Liste als Default, oder Query(default=None), um fehlende Werte zuzulassen.
from typing import List
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items")
def list_items(q: List[str] = Query(default=[])):
return {"q": q}
# GET /items?q=a&q=b&q=c -> {"q": ["a", "b", "c"]}
# declare default=None to accept a list or nullErforderliche Query-Parameter
Query(...) (der Ellipsis) deklariert einen erforderlichen Query-Parameter mit Validierungs-Metadaten. Ohne Default und ohne Query(...) ist auch ein plain annotierter Parameter erforderlich.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items")
def read_item(q: str = Query(...)):
return {"q": q}
# GET /items?q=hello -> ok
# GET /items -> 422 (q is required)
# Query(...) (Ellipsis) marks a parameter as requiredRequest-Body (Pydantic)
BaseModel-Grundlagen
Ein als Funktionsparameter deklarierter Pydantic-BaseModel wird zum JSON-Request-Body. FastAPI validiert die Payload, konvertiert Typen und gibt bei ungültigen Daten 422. Felder mit Default sind optional.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
in_stock: bool = True
app = FastAPI()
@app.post("/items")
def create_item(item: Item):
return item
# POST /items body: {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5, "in_stock": true}Feldtypen & Constraints
Field() ergänzt Constraints und Metadaten zu Modell-Attributen: min_length/max_length für Strings, gt/ge/lt/le für Zahlen, default_factory für veränderliche Defaults. model_config mit json_schema_extra ergänzt Beispiele in den Docs.
from pydantic import BaseModel, Field
from typing import Optional
class Item(BaseModel):
name: str = Field(min_length=1, max_length=100)
price: float = Field(gt=0, description="must be positive")
tax: Optional[float] = None
tags: list[str] = Field(default_factory=list)
model_config = {
"json_schema_extra": {
"examples": [{"name": "Apple", "price": 0.5, "tags": ["fruit"]}]
}
}Verschachtelte Models
Models lassen sich verschachteln: einen weiteren BaseModel als Feldtyp deklarieren. FastAPI validiert die volle verschachtelte Struktur rekursiv, und das erzeugte OpenAPI-Schema spiegelt die verschachtelten Objekte.
from pydantic import BaseModel
from typing import Optional
class Image(BaseModel):
url: str
name: str
class Item(BaseModel):
name: str
description: Optional[str] = None
image: Optional[Image] = None
images: list[Image] = []
# valid body:
# {"name": "Phone", "image": {"url": "http://x/a.png", "name": "a"}}Feld-Validierung
@field_validator (Pydantic v2) ergänzt eigene Validierungslogik pro Feld. ValueError werfen, um Input abzulehnen (FastAPI zeigt es als 422). Den (ggf. transformierten) Wert zurückgeben, um ihn zu behalten.
from pydantic import BaseModel, field_validator
class User(BaseModel):
name: str
email: str
@field_validator("email")
@classmethod
def email_must_contain_at(cls, v: str) -> str:
if "@" not in v:
raise ValueError("must contain @")
return v.lower()
@field_validator("name")
@classmethod
def name_stripped(cls, v: str) -> str:
return v.strip()Optionale & Default-Felder
Ein Feld ist nur erforderlich, wenn es keinen Default hat und nicht Optional ist. Optional[str] = None ist das Standardmuster für ein optionales nullable Feld; ein plain Default wie 0.0 macht ein Feld optional mit diesem Wert.
from pydantic import BaseModel
from typing import Optional
class Item(BaseModel):
name: str # required
description: Optional[str] = None # optional, defaults to None
price: float = 0.0 # optional, defaults to 0.0
tags: list[str] = [] # optional, defaults to empty list
# All of these are valid:
# {"name": "X"}
# {"name": "X", "price": 9.99, "tags": ["a"]}Body mit Path & Query
Path-, Query- und Body-Parameter koexistieren in einer Operation. FastAPI entscheidet: Pfadparameter, wenn im Pfad; Pydantic-Model (oder Body()) für den Body; sonst Query. Optionaler Body braucht None als Default.
from fastapi import FastAPI, Path, Query
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
app = FastAPI()
@app.put("/items/{item_id}")
def update_item(
item_id: int = Path(ge=1),
q: Optional[str] = Query(default=None),
item: Item = None,
):
result = {"item_id": item_id, **item.model_dump()}
if q:
result["q"] = q
return resultResponse Model
response_model-Grundlagen
response_model filtert die zurückgegebenen Daten auf die im Model definierten Felder, auch wenn du ein Objekt mit zusätzlichen Feldern zurückgibst. Der Standardweg, um sensible Felder wie Passwörter zu verbergen.
from fastapi import FastAPI
from pydantic import BaseModel
class User(BaseModel):
username: str
email: str
hashed_password: str
class UserOut(BaseModel):
username: str
email: str
app = FastAPI()
@app.get("/users/me", response_model=UserOut)
def read_user():
return User(username="bob", email="[email protected]", hashed_password="secret")
# response: {"username": "bob", "email": "[email protected]"} (no password)Felder ausschließen
response_model_include und response_model_exclude erlauben Whitelist/Blacklist von Feldern pro Route, ohne neue Models zu definieren. Eine Menge von Feldnamen übergeben. Sie wirken zusätzlich zum response_model.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
secret: str
app = FastAPI()
@app.get("/items/{id}", response_model=Item, response_model_exclude={"secret"})
def read_item(id: int):
return {"name": "Apple", "price": 0.5, "secret": "hidden"}
@app.get("/items", response_model=list[Item], response_model_include={"name", "price"})
def list_items():
return [{"name": "Apple", "price": 0.5, "secret": "x"}]Listen-Antwort
response_model=list[Model] (oder List[Model]) deklariert, dass ein Endpunkt ein Array von Objekten zurückgibt. FastAPI validiert und serialisiert jedes Element der Liste.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
app = FastAPI()
@app.get("/items", response_model=list[Item])
def list_items():
return [
{"name": "Apple", "price": 0.5},
{"name": "Banana", "price": 0.3},
]
# response: [{"name": "Apple", "price": 0.5}, {"name": "Banana", "price": 0.3}]Unset/Defaults ausschließen
exclude_unset lässt Felder weg, die der Client nie gesendet hat (nur explizit gesetzte erscheinen). exclude_defaults lässt Felder weg, die ihrem Default entsprechen; exclude_none lässt None-Felder weg. Praktisch für schlanke Antworten.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
description: str | None = None
price: float = 0.0
tax: float = 0.0
app = FastAPI()
@app.get("/items/{id}", response_model=Item, response_model_exclude_unset=True)
def read_item(id: int):
return {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5} (description, tax omitted)
# also: response_model_exclude_defaults=True
# response_model_exclude_none=TrueAntwort per Alias
Field(alias=...) lässt eingehendes JSON einen anderen Key-Namen als das Python-Attribut nutzen. response_model_by_alias=True gibt auch per Alias aus. populate_by_name=True erlaubt zusätzlich den originalen Attributnamen beim Input.
from fastapi import FastAPI
from pydantic import BaseModel, ConfigDict, Field
class Item(BaseModel):
model_config = ConfigDict(populate_by_name=True)
name: str = Field(alias="itemName")
price: float
app = FastAPI()
@app.post("/items", response_model=Item, response_model_by_alias=True)
def create(item: Item):
return item
# input: {"itemName": "Apple", "price": 0.5}
# output: {"itemName": "Apple", "price": 0.5}Plain-Dict-Antwort
Ein zurückgegebenes Dict/Liste serialisiert automatisch zu JSON. response_class ändert den Standard-Antworttyp (HTMLResponse, PlainTextResponse), oder direkt eine Response-Unterklasse für volle Kontrolle.
from fastapi import FastAPI
from fastapi.responses import JSONResponse, PlainTextResponse
app = FastAPI()
@app.get("/dict")
def dict_resp():
return {"a": 1, "b": 2} # auto JSON
@app.get("/text", response_class=PlainTextResponse)
def text_resp():
return "plain text response"
@app.get("/raw")
def raw_resp():
return JSONResponse(content={"a": 1}, status_code=200)Form & UploadFile
Formular-Daten
Form() deklariert einen Parameter aus application/x-www-form-urlencoded- oder multipart-Formulardaten. Form() lässt sich nicht mit einem JSON-Body (BaseModel) in derselben Operation mischen — ein Content-Typ wählen.
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login")
def login(username: str = Form(), password: str = Form()):
return {"username": username}
# Content-Type: application/x-www-form-urlencoded
# body: username=bob&password=secretUploadFile-Grundlagen
UploadFile ist eine Streaming-Datei-Repräsentation mit .filename, .content_type, .read(), .write(), .close(). Innerhalb von async def 'await file.read()' verwenden. Bei großen Dateien file.file (SpooledTemporaryFile) bevorzugen, um nicht alles in den Speicher zu laden.
from fastapi import FastAPI, UploadFile, File
app = FastAPI()
@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):
contents = await file.read()
return {
"filename": file.filename,
"size": len(contents),
"content_type": file.content_type,
}Mehrere Dateien
list[UploadFile] deklarieren, um mehrere Dateien in einer Anfrage zu akzeptieren. Jede Datei wird mit demselben Feldnamen gesendet. Die Reihenfolge in der Liste entspricht der Sende-Reihenfolge.
from fastapi import FastAPI, UploadFile
app = FastAPI()
@app.post("/uploads")
async def upload_many(files: list[UploadFile]):
return [
{"filename": f.filename, "size": len(await f.read())}
for f in files
]
# curl: curl -F "[email protected]" -F "[email protected]" http://localhost:8000/uploadsFile und Form zusammen
Form() und UploadFile (File()) lassen sich im selben Endpunkt kombinieren, weil beide multipart/form-data nutzen. Mit einem JSON-BaseModel-Body lassen sie sich weiterhin nicht kombinieren.
from fastapi import FastAPI, UploadFile, File, Form
app = FastAPI()
@app.post("/items")
async def create_item(
name: str = Form(),
description: str = Form(),
file: UploadFile = File(),
):
return {
"name": name,
"description": description,
"file": file.filename,
}Hochgeladene Datei speichern
Bei kleinen Dateien streamt shutil.copyfileobj das SpooledTemporaryFile effizient auf die Platte. Bei sehr großen Dateien in Chunks lesen (z. B. 1MB), um den Speicher niedrig zu halten. file.filename immer bereinigen, um Path-Traversal zu vermeiden.
import shutil
from pathlib import Path
from fastapi import FastAPI, UploadFile
app = FastAPI()
@app.post("/save")
async def save_file(file: UploadFile):
dest = Path("uploads") / file.filename
dest.parent.mkdir(exist_ok=True)
with dest.open("wb") as buf:
shutil.copyfileobj(file.file, buf)
return {"saved_to": str(dest)}
# async alternative for large files:
# async with dest.open("wb") as buf:
# while chunk := await file.read(1024 * 1024):
# buf.write(chunk)Datei-Metadaten & Größe
file.content_type und Größe vor der Verarbeitung validieren. Nach read() steht der Cursor am Ende; 'await file.seek(0)' zurückspulen, falls erneut gelesen werden soll. Echte Typprüfung inspiziert Magic Bytes, nicht nur den Header.
from fastapi import FastAPI, UploadFile, File
app = FastAPI()
@app.post("/validate")
async def validate(file: UploadFile = File(...)):
# allowed types
allowed = {"image/png", "image/jpeg"}
if file.content_type not in allowed:
return {"error": "unsupported type"}
contents = await file.read()
max_size = 5 * 1024 * 1024 # 5 MB
if len(contents) > max_size:
return {"error": "file too large"}
await file.seek(0) # rewind so later reads work
return {"filename": file.filename, "size": len(contents)}Dependency Injection
Grundlegendes Depends
Depends() injiziert den Rückgabewert einer Funktion in deine path operation. Geteilte Logik (Pagination, Parsing, DB-Sessions) liegt an einem Ort und wird über Endpunkte wiederverwendet. Die Parameter der Dependency sind auch in OpenAPI dokumentiert.
from fastapi import FastAPI, Depends
app = FastAPI()
def common_params(q: str | None = None, skip: int = 0, limit: int = 10):
return {"q": q, "skip": skip, "limit": limit}
@app.get("/items")
def list_items(commons: dict = Depends(common_params)):
return commons
@app.get("/users")
def list_users(commons: dict = Depends(common_params)):
return commonsKlassen-Dependencies
Eine Klasse mit __init__ kann eine Dependency sein; FastAPI ruft sie wie eine Funktion auf. Depends(CommonQueryParams) oder die Kurzfassung Depends() verwenden, wenn der Parameter mit der Klasse annotiert ist. Die Instanz wird injiziert.
from fastapi import FastAPI, Depends
class CommonQueryParams:
def __init__(self, q: str | None = None, skip: int = 0, limit: int = 10):
self.q = q
self.skip = skip
self.limit = limit
app = FastAPI()
@app.get("/items")
def list_items(commons: CommonQueryParams = Depends(CommonQueryParams)):
return {"q": commons.q, "skip": commons.skip, "limit": commons.limit}
# shorthand: commons = Depends() infers the typeVerschachtelte Dependencies
Dependencies können selbst von anderen Dependencies abhängen und bilden so einen Graphen. FastAPI löst den ganzen Baum auf, cachet jedes Ergebnis pro Anfrage und propagiert Ausnahmen. Ideal für geschichtete Auth (token -> user -> permissions).
from fastapi import FastAPI, Depends, Header, HTTPException
def get_token(authorization: str = Header()):
if not authorization.startswith("Bearer "):
raise HTTPException(status_code=401, detail="invalid header")
return authorization.removeprefix("Bearer ")
def get_current_user(token: str = Depends(get_token)):
if token != "admin-token":
raise HTTPException(status_code=403, detail="forbidden")
return {"username": "admin"}
app = FastAPI()
@app.get("/me")
def me(user: dict = Depends(get_current_user)):
return userYield-Dependencies (Cleanup)
Ein Dependency-Generator (yield) ist perfekt für Ressourcen mit Aufräumbedarf: DB-Sessions, Datei-Handles, Transaktionen. Code nach yield läuft als Finalizer, selbst wenn die Route eine Ausnahme wirft. Nur ein yield pro Dependency.
from fastapi import FastAPI, Depends
def get_db():
db = open_db_session() # acquire resource
try:
yield db # injected into the route
finally:
db.close() # always runs after the request
app = FastAPI()
@app.get("/items")
def list_items(db = Depends(get_db)):
return db.query("SELECT * FROM items")Globale Dependencies
dependencies=[...] an FastAPI() (oder einen APIRouter) übergeben, um sie auf jeder Route zu erzwingen, ohne den Rückgabewert zu injizieren. Nützlich für globale Auth, Rate Limiting oder Request-Logging.
from fastapi import FastAPI, Depends, Header, HTTPException
def verify_token(x_token: str = Header()):
if x_token != "supersecret":
raise HTTPException(status_code=400, detail="X-Token missing")
def verify_key(x_key: str = Header()):
if x_key != "realkey":
raise HTTPException(status_code=400, detail="X-Key missing")
# applied to every route in the app
app = FastAPI(dependencies=[Depends(verify_token), Depends(verify_key)])
@app.get("/items")
def list_items():
return [{"item": "a"}] # token & key already checkedDependencies pro Route
dependencies=[Depends(...)] auf einem Decorator (oder APIRouter) verlangt eine Dependency für konkrete Routen, ohne ihren Rückgabewert zu nutzen. So bleiben die Routen-Signaturen sauber, während Checks durchgesetzt werden.
from fastapi import FastAPI, Depends, Header, HTTPException
def verify_token(x_token: str = Header()):
if x_token != "secret":
raise HTTPException(status_code=401, detail="bad token")
app = FastAPI()
@app.get("/public")
def public():
return {"open": True}
@app.get("/private", dependencies=[Depends(verify_token)])
def private():
return {"secret": "data"}Sicherheit (HTTPBasic / OAuth2 / JWT)
HTTP Basic Auth
HTTPBasic parst den Authorization: Basic Header in username/password. secrets.compare_digest (nicht ==) verwenden, um Timing-Attacken zu verhindern. Immer 401 mit WWW-Authenticate: Basic zurückgeben, damit Browser nach Credentials fragen.
import secrets
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials
security = HTTPBasic()
app = FastAPI()
def get_current_user(credentials: HTTPBasicCredentials = Depends(security)):
correct_user = secrets.compare_digest(credentials.username, "admin")
correct_pass = secrets.compare_digest(credentials.password, "secret")
if not (correct_user and correct_pass):
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid credentials",
headers={"WWW-Authenticate": "Basic"},
)
return credentials.username
@app.get("/profile")
def profile(user: str = Depends(get_current_user)):
return {"user": user}OAuth2PasswordBearer
OAuth2PasswordBearer deklariert, dass Routen einen Bearer-Token erwarten; die Dependency extrahiert ihn aus dem Authorization-Header. tokenUrl sagt der Docs-UI, wohin Credentials gesendet werden. Der Token ist erstmal nur ein String, bis du ihn validierst.
from fastapi import FastAPI, Depends
from fastapi.security import OAuth2PasswordBearer
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
app = FastAPI()
@app.get("/me")
def me(token: str = Depends(oauth2_scheme)):
return {"token": token}
# client POSTs username+password to /token, receives an access token,
# then sends it as: Authorization: Bearer <token>JWT-Token erzeugen
python-jose (oder PyJWT) zum Signieren von Tokens. Der 'sub' (subject) Claim hält üblicherweise username oder user id, 'exp' setzt den Ablauf. SECRET_KEY lang, zufällig und aus der Umgebung laden — niemals committen.
from datetime import datetime, timedelta, timezone
from jose import jwt
SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"
def create_access_token(data: dict, expires_minutes: int = 30) -> str:
to_encode = data.copy()
expire = datetime.now(timezone.utc) + timedelta(minutes=expires_minutes)
to_encode.update({"exp": expire})
return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
# token = create_access_token({"sub": "alice"})
# -> eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...JWT-Token dekodieren
jwt.decode verifiziert Signatur und 'exp'-Claim automatisch und wirft bei Fehlschlag JWTError. Die Dependency auf eine 401 mit WWW-Authenticate: Bearer mappen, damit Clients wissen, dass sie einen gültigen Token liefern müssen.
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import jwt, JWTError
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"
def get_current_user(token: str = Depends(oauth2_scheme)) -> str:
try:
payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
username: str | None = payload.get("sub")
if username is None:
raise credentials_exception
return username
except JWTError:
raise credentials_exception
credentials_exception = HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Could not validate credentials",
headers={"WWW-Authenticate": "Bearer"},
)Passwort-Hashing
Passwörter niemals im Klartext speichern. passlib mit bcrypt (oder argon2) übernimmt Salting und Hashing. verify() vergleicht Klartext-Input mit einem gespeicherten Hash. pip install passlib[bcrypt] für das bcrypt-Backend.
from passlib.context import CryptContext
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
def hash_password(plain: str) -> str:
return pwd_context.hash(plain)
def verify_password(plain: str, hashed: str) -> bool:
return pwd_context.verify(plain, hashed)
# usage when issuing tokens:
def authenticate_user(username: str, password: str):
user = fake_db.get(username)
if not user or not verify_password(password, user.hashed_password):
return False
return userOAuth2-Login-Fluss
OAuth2PasswordRequestForm liest username/password aus einem form-kodierten POST (der Standard-OAuth2-Passwort-Fluss). access_token und token_type: 'bearer' zurückgeben. Dieser Endpunkt ist das Ziel von tokenUrl in OAuth2PasswordBearer.
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm
app = FastAPI()
@app.post("/token")
def login(form: OAuth2PasswordRequestForm = Depends()):
user = authenticate_user(form.username, form.password)
if not user:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Incorrect username or password",
)
token = create_access_token({"sub": user.username})
return {"access_token": token, "token_type": "bearer"}
# OAuth2PasswordRequestForm parses username+password from form data
# and powers the 'Authorize' button in the Swagger UI.Middleware
Middleware ergänzen
@app.middleware('http') registriert eine Funktion, die jede Anfrage umwickelt. Sie muss await call_next(request) aufrufen, um die Antwort zu bekommen, kann sie dann inspizieren oder ändern. Middleware läuft für alle Routen.
import time
from fastapi import FastAPI, Request
app = FastAPI()
@app.middleware("http")
async def add_process_time(request: Request, call_next):
start = time.perf_counter()
response = await call_next(request)
duration = time.perf_counter() - start
response.headers["X-Process-Time"] = f"{duration:.4f}"
return responseEigener Header-Middleware
Middleware ist der richtige Ort für Header, die auf jeder Antwort stehen sollen (Security-Header, Server-Banner, Tracing-IDs). Das Response-Objekt nach await call_next verändern.
from fastapi import FastAPI, Request
app = FastAPI()
@app.middleware("http")
async def add_banner(request: Request, call_next):
response = await call_next(request)
response.headers["X-Powered-By"] = "FastAPI"
response.headers["X-Frame-Options"] = "DENY"
return response
# every response now carries these headersBaseHTTPMiddleware
Für wiederverwendbare, konfigurierbare Middleware BaseHTTPMiddleware ableiten und mit app.add_middleware(MyMiddleware, **options) registrieren. So werden auch die eingebauten CORS-, GZip- und TrustedHost-Middlewares ergänzt.
from starlette.middleware.base import BaseHTTPMiddleware
from fastapi import FastAPI, Request
class TimingMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request: Request, call_next):
start = time.perf_counter()
response = await call_next(request)
response.headers["X-Duration"] = str(time.perf_counter() - start)
return response
app = FastAPI()
app.add_middleware(TimingMiddleware)
# class-based middleware is reusable and configurableHTTPS-Redirect
HTTPSRedirectMiddleware gibt für jede HTTP-Anfrage eine 308-Weiterleitung zur HTTPS-Version zurück. Hinter einem Load Balancer, der TLS terminiert, verwenden, damit Clients auf eine sichere Verbindung hochstufen.
from fastapi import FastAPI
from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware
app = FastAPI()
app.add_middleware(HTTPSRedirectMiddleware)
# all HTTP requests are redirected to HTTPS (308)Trusted Host
TrustedHostMiddleware weist Anfragen ab, deren Host-Header nicht in der Allow-Liste steht, und verhindert Host-Header-Injection-Angriffe. Wildcards wie '*.example.com' werden unterstützt. 'localhost' für lokale Entwicklung immer aufnehmen.
from fastapi import FastAPI
from fastapi.middleware.trustedhost import TrustedHostMiddleware
app = FastAPI()
app.add_middleware(
TrustedHostMiddleware,
allowed_hosts=["example.com", "*.example.com", "localhost"],
)
# requests with a disallowed Host header get a 400 responseMiddleware-Reihenfolge
Starlette führt Middleware für eingehende Anfragen in LIFO-Reihenfolge aus: die zuletzt ergänzte läuft zuerst. CORS früh ergänzen (damit Preflight funktioniert), GZip danach. Beim Debuggen daran denken, warum ein Header einer Middleware von einer anderen nicht gesehen wird.
from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
# Middleware runs in REVERSE order of registration for requests,
# and in registration order for responses.
app.add_middleware(GZipMiddleware, minimum_size=1000)
app.add_middleware(CORSMiddleware, allow_origins=["*"])
# request flow: CORS -> GZip -> route
# response flow: route -> GZip -> CORSCORS
CORSMiddleware-Setup
CORSMiddleware behandelt den CORS-Preflight (OPTIONS) und ergänzt Access-Control-*-Header. allow_origins sollte die exakt erlaubten Ursprünge listen; in Produktion eine Liste konkreter URLs statt ['*'] verwenden.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://example.com", "https://www.example.com"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
@app.get("/api/data")
def data():
return {"data": 1}Alle Ursprünge erlauben (nur Dev)
allow_origins=['*'] erlaubt jeden Ursprung, kann aber nicht mit allow_credentials=True kombiniert werden (Browser lehnen es ab). Nur für völlig öffentliche APIs in der Entwicklung; in Produktion die realen Ursprünge aufzählen.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
# allow_credentials=True CANNOT be combined with allow_origins=["*"]
)Credentials erlauben
allow_credentials=True lässt den Browser Cookies und Authorization-Header cross-origin senden. Es verlangt konkrete Ursprünge (niemals '*'). Der Browser setzt Access-Control-Allow-Credentials: true auf Antworten.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_credentials=True, # send cookies / Authorization
allow_methods=["GET", "POST"],
allow_headers=["Authorization", "Content-Type"],
)
# needed when the frontend sends cookies or credentials with requestsErlaubte Methoden & Header
allow_methods/allow_headers beschränken, was der Browser senden darf. expose_headers listet Response-Header, die das Frontend-JavaScript lesen darf (Browser verbergen sonst eigene Header). Preflight-Antworten werden vom Browser gecacht.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
allow_headers=["Authorization", "Content-Type", "X-Request-ID"],
expose_headers=["X-Total-Count", "X-Process-Time"],
)
# expose_headers lets the frontend JS read these response headersPreflight-Anfragen
Für 'non-simple'-Anfragen (eigene Header, PUT/DELETE, JSON-Content-Type) sendet der Browser einen OPTIONS-Preflight. CORSMiddleware fängt OPTIONS ab und antwortet mit den erlaubten Methoden/Headern. max_age steuert, wie lange der Browser die Antwort cached.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_methods=["*"],
allow_headers=["*"],
max_age=600, # browser caches preflight result for 600s
)
# Browser sends OPTIONS preflight for non-simple requests;
# CORSMiddleware answers automatically with the right headers.Dynamische Origin-Validierung
Für dynamische Allow-Listen allow_origin_regex (matcht gegen den Origin der Anfrage) statt einer statischen Liste verwenden. Praktisch, wenn gültige Ursprünge einem Muster folgen (z. B. jede Subdomain von example.com).
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
VALID_DOMAINS = {"example.com", "staging.example.com"}
def origin_check(origin: str) -> str | None:
if origin and origin.replace("https://", "").replace("http://", "") in VALID_DOMAINS:
return origin
return None
app.add_middleware(
CORSMiddleware,
allow_origin_regex=r"https://.*\.example\.com",
allow_methods=["*"],
allow_headers=["*"],
)Ausnahmebehandlung
HTTPException werfen
raise HTTPException irgendwo in einer Route oder Dependency, um kurzzuschließen und eine Fehlerantwort zurückzugeben. detail kann ein String, Dict oder Liste sein — es wird zum JSON-'detail'-Feld. headers ergänzt optional Response-Header.
from fastapi import FastAPI, HTTPException, status
app = FastAPI()
items = {1: "Apple", 2: "Banana"}
@app.get("/items/{item_id}")
def read_item(item_id: int):
if item_id not in items:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="Item not found",
headers={"X-Error": "missing"},
)
return {"item": items[item_id]}Eigene Ausnahme
Einen Handler mit @app.exception_handler(MyException) registrieren, um jede eigene Ausnahme in eine HTTP-Antwort umzuwandeln. Der Handler erhält die Anfrage und die Ausnahme. So wird Fehlerformatierung für Domänen-Fehler zentralisiert.
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
class UnicornException(Exception):
def __init__(self, name: str):
self.name = name
app = FastAPI()
@app.exception_handler(UnicornException)
async def unicorn_handler(request: Request, exc: UnicornException):
return JSONResponse(
status_code=418,
content={"message": f"Oops, {exc.name} did it again"},
)
@app.get("/unicorns/{name}")
def read_unicorn(name: str):
if name == "yolo":
raise UnicornException(name=name)
return {"name": name}Validierungs-Fehler überschreiben
RequestValidationError wird geworfen, wenn Input die Pydantic-Validierung nicht besteht. Seinen Handler mit @app.exception_handler(RequestValidationError) überschreiben, um die 422-Antwortform anzupassen, z. B. an einen firmenweiten Error-Envelope.
from fastapi import FastAPI, Request, status
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
app = FastAPI()
@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
return JSONResponse(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
content={
"success": False,
"errors": exc.errors(),
"body": exc.body,
},
)HTTPException-Handler überschreiben
Den Default-HTTPException-Handler überschreiben, um eine konsistente Fehler-JSON-Form über alle geworfenen HTTPExceptions durchzusetzen. Beim Neu-Binden die Klasse als fastapi.exceptions.HTTPException importieren (dieselbe, die raise nutzt).
from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse
from fastapi.exceptions import HTTPException as FastAPIHTTPException
app = FastAPI()
@app.exception_handler(FastAPIHTTPException)
async def custom_http_handler(request, exc: FastAPIHTTPException):
return JSONResponse(
status_code=exc.status_code,
content={
"success": False,
"status": exc.status_code,
"message": exc.detail,
},
headers=exc.headers,
)Häufige Statuscodes
Das status-Modul liefert benannte Konstanten für alle HTTP-Statuscodes und vermeidet magische Zahlen. 200 (Default GET), 201 (created), 204 (no content), 422 (validation) sind in FastAPI-Apps die häufigsten.
from fastapi import FastAPI, status
app = FastAPI()
@app.get("/ok", status_code=status.HTTP_200_OK)
def ok(): return {"ok": True}
@app.post("/create", status_code=status.HTTP_201_CREATED)
def create(): return {"id": 1}
@app.get("/no-content", status_code=status.HTTP_204_NO_CONTENT)
def no_content(): return None
@app.get("/not-found")
def missing():
# raise HTTPException(status.HTTP_404_NOT_FOUND, "nope")
...
# Other common: 400 BAD_REQUEST, 401 UNAUTHORIZED,
# 403 FORBIDDEN, 409 CONFLICT, 422 UNPROCESSABLE_ENTITY, 500 INTERNAL_SERVER_ERRORGenerischer Exception-Handler
Ein Handler für die Basis-Exception fängt alles Unbehandelte und verhindert, dass Stack-Traces zu Clients durchsickern. Den vollen Traceback immer serverseitig loggen; dem Client eine generische 500 zurückgeben.
import logging
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
logger = logging.getLogger("uvicorn.error")
app = FastAPI()
@app.exception_handler(Exception)
async def unhandled(request: Request, exc: Exception):
logger.exception("Unhandled error on %s", request.url.path)
return JSONResponse(
status_code=500,
content={"detail": "Internal Server Error"},
)
@app.get("/boom")
def boom():
raise RuntimeError("something exploded")Background Tasks
Grundlegendes BackgroundTasks
BackgroundTasks führt Funktionen aus, nachdem die Antwort gesendet wurde — perfekt für Fire-and-Forget-Arbeit wie Logging, E-Mails oder Cache-Invalidierung. add_task plant eine Funktion (und Argumente), ohne die Antwort zu blockieren.
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
def write_log(message: str):
with open("log.txt", "a") as f:
f.write(message + "\n")
@app.post("/send")
def send_notification(background_tasks: BackgroundTasks):
background_tasks.add_task(write_log, "notification sent")
return {"message": "notification queued"}Mehrere Tasks
So viele Tasks ergänzen wie gewünscht; sie laufen sequenziell in Ergänzungs-Reihenfolge, nachdem die Antwort zurückgegeben wurde. Weil sie im selben Prozess laufen, sie kurz und nicht-blockierend halten oder auf eine echte Queue umsteigen (Celery, RQ, Dramatiq).
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
def send_email(to: str, subject: str): ...
def update_cache(key: str): ...
def notify_slack(msg: str): ...
@app.post("/signup")
def signup(background_tasks: BackgroundTasks):
background_tasks.add_task(send_email, "[email protected]", "Welcome")
background_tasks.add_task(update_cache, "user_count")
background_tasks.add_task(notify_slack, "new signup")
return {"status": "ok"}Task mit Dependencies
BackgroundTasks wird wie jede andere Dependency injiziert. Die Task-Funktion kann Werte (wie eine DB-Session) erhalten, die zur Anfragezeit erfasst wurden. Hinweis: yield/close-Ressourcen aus Dependencies schließen erst nach Task-Ende, da Tasks im Lebenszyklus-Scopes der Anfrage laufen.
from fastapi import FastAPI, BackgroundTasks, Depends
app = FastAPI()
def get_db_session():
db = "session"
yield db
def write_log(db, message: str):
print(db, message)
@app.get("/items")
def list_items(background_tasks: BackgroundTasks, db = Depends(get_db_session)):
background_tasks.add_task(write_log, db, "list called")
return {"items": []}Async-Task-Funktion
Background-Task-Funktionen können sync (läuft im Threadpool) oder async (awaited auf der Event-Loop) sein. Async-Tasks für I/O-lastige Arbeit, die selbst async-Bibliotheken nutzt, sync-Tasks für CPU-/blockierende Arbeit.
from fastapi import FastAPI, BackgroundTasks
import httpx
app = FastAPI()
async def fetch_url(url: str):
async with httpx.AsyncClient() as client:
r = await client.get(url)
return r.status_code
@app.post("/webhook")
def webhook(url: str, background_tasks: BackgroundTasks):
background_tasks.add_task(fetch_url, url)
return {"queued": url}Background vs. Celery
BackgroundTasks für leichtgewichtige, unkritische Arbeit, die bei Neustart verloren gehen darf. Für Jobs, die Crashes überleben, Retries oder Maschinen-übergreifende Skalierung brauchen, eine echte Task-Queue (Celery, RQ, Dramatiq, Arq) mit einem Broker wie Redis oder RabbitMQ.
# BackgroundTasks: in-process, no broker, lost if process crashes
@app.post("/quick")
def quick(tasks: BackgroundTasks):
tasks.add_task(small_job)
return {"ok": True}
# Celery/RQ/Dramatiq: separate workers, persistent, retryable
# from celery import Celery
# @celery.task
# def big_job(payload): ...
#
# @app.post("/heavy")
# def heavy(payload: dict):
# big_job.delay(payload)
# return {"queued": True}E-Mail-Versand-Beispiel
E-Mail-Versand ist der klassische BackgroundTasks-Fall: langsam, und der Nutzer soll nicht warten. Die Antwort kommt sofort, während die E-Mail danach rausgeht. Bei hohem Volumen eine Queue und ein E-Mail-Service-SDK mit Retries bevorzugen.
from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel, EmailStr
class Message(BaseModel):
to: EmailStr
subject: str
body: str
app = FastAPI()
def send_email(to: str, subject: str, body: str):
# smtplib or your provider's SDK
import smtplib
with smtplib.SMTP("localhost") as s:
s.sendmail("[email protected]", to, f"Subject: {subject}\n\n{body}")
@app.post("/contact")
def contact(msg: Message, tasks: BackgroundTasks):
tasks.add_task(send_email, msg.to, msg.subject, msg.body)
return {"status": "queued", "to": msg.to}WebSocket
WebSocket-Grundlagen
@app.websocket() definiert einen WebSocket-Endpunkt. Vor Senden/Empfangen muss accept() aufgerufen werden. Die Funktion looped typischerweise lesend; receive_text/receive_bytes/receive_json awaiten alle Daten vom Client.
from fastapi import FastAPI, WebSocket
app = FastAPI()
@app.websocket("/ws")
async def websocket_endpoint(ws: WebSocket):
await ws.accept()
while True:
data = await ws.receive_text()
await ws.send_text(f"echo: {data}")
# client (browser):
# const ws = new WebSocket("ws://localhost:8000/ws");
# ws.onmessage = (e) => console.log(e.data);JSON senden
send_json() und receive_json() übernehmen die Serialisierung und tauschen JSON-Objekte über den Socket aus. Für Binärdaten send_bytes/receive_bytes. Jedes send/receive ist ein separater Frame auf dem WebSocket.
import json
from fastapi import FastAPI, WebSocket
app = FastAPI()
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
await ws.accept()
while True:
msg = await ws.receive_json()
await ws.send_json({"reply": msg.get("text", "").upper()})
# send_text / send_bytes / send_json helpers are availableWebSocket schließen
WebSocketDisconnect wird geworfen, wenn der Client die Verbindung schließt — fangen, um aufzuräumen. ws.close(code=1000) für einen normalen Abschluss; übliche Codes: 1000 (normal), 1008 (policy violation), 1011 (server error).
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
app = FastAPI()
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
await ws.accept()
try:
while True:
data = await ws.receive_text()
if data == "quit":
await ws.close(code=1000)
break
await ws.send_text(data)
except WebSocketDisconnect:
print("client disconnected")Connection-Manager
Ein ConnectionManager verfolgt aktive Sockets, damit man an alle verbundenen Clients broadcasten kann (z. B. ein Chatraum). Den Socket bei Disconnect immer entfernen, um nicht an geschlossene Verbindungen zu senden und Speicher begrenzt zu halten.
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
class ConnectionManager:
def __init__(self):
self.active: list[WebSocket] = []
async def connect(self, ws: WebSocket):
await ws.accept()
self.active.append(ws)
def disconnect(self, ws: WebSocket):
self.active.remove(ws)
async def broadcast(self, message: str):
for ws in self.active:
await ws.send_text(message)
manager = ConnectionManager()
app = FastAPI()
@app.websocket("/chat")
async def chat(ws: WebSocket):
await manager.connect(ws)
try:
while True:
msg = await ws.receive_text()
await manager.broadcast(msg)
except WebSocketDisconnect:
manager.disconnect(ws)WebSocket-Auth per Query-Param
Browser können bei WebSocket-Verbindungen keine eigenen Header setzen, daher laufen Auth-Tokens üblicherweise als Query-Parameter (oder Cookies). Vor accept() validieren und bei Unautorisierung mit Code 1008 (policy violation) schließen.
from fastapi import FastAPI, WebSocket, WebSocketDisconnect, HTTPException
app = FastAPI()
async def authenticate(token: str) -> str:
if token != "secret":
raise HTTPException(status_code=401)
return "alice"
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
token = ws.query_params.get("token")
if not token:
await ws.close(code=1008)
return
user = await authenticate(token)
await ws.accept()
try:
while True:
data = await ws.receive_text()
await ws.send_text(f"{user}: {data}")
except WebSocketDisconnect:
passWebSocket mit Dependencies
Dependencies funktionieren in WebSocket-Endpunkten wie in HTTP-Routen, aber nur solche, die aus dem initialen Handshake lesen (Header, Query-Params, Cookies) machen Sinn — es gibt keinen Body. Üblich über Depends() injizieren.
from fastapi import FastAPI, WebSocket, Depends, Header
app = FastAPI()
def token_validator(token: str = Header(default="")):
# for WS, headers come from the initial HTTP handshake
return token == "valid"
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket, valid: bool = Depends(token_validator)):
if not valid:
await ws.close(code=1008)
return
await ws.accept()
while True:
msg = await ws.receive_text()
await ws.send_text(msg)Datenbank (SQLAlchemy)
SQLAlchemy-Setup
create_engine richtet den DB-Verbindungspool ein; SessionLocal ist eine Factory für Sessions; Base ist das deklarative Basis für Models. Für SQLite mit FastAPI check_same_thread=False setzen, weil Anfragen in verschiedenen Threads laufen können.
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base
SQLALCHEMY_DATABASE_URL = "sqlite:///./app.db"
# postgresql: "postgresql://user:pass@localhost:5432/dbname"
engine = create_engine(
SQLALCHEMY_DATABASE_URL,
connect_args={"check_same_thread": False}, # sqlite only
)
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
Base = declarative_base()Session-Dependency
Eine yield-Dependency ist der kanonische Weg, eine DB-Session bereitzustellen: jede Anfrage bekommt eine frische Session, die im finally-Block geschlossen wird. Das garantiert Aufräumen, selbst wenn die Route eine Ausnahme wirft.
from fastapi import Depends
from sqlalchemy.orm import Session
def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close()
@app.get("/items")
def list_items(db: Session = Depends(get_db)):
return db.query(Item).all()
# each request gets its own session, closed automatically afterwardModel-Definition
Tabellen als SQLAlchemy-ORM-Models definieren, die Base ableiten. In Produktion Alembic für Schema-Migrationen statt create_all(). Spalten können indexiert, nullable sein und Defaults auf DB- oder Python-Ebene bekommen.
from sqlalchemy import Column, Integer, String, Boolean
from sqlalchemy.orm import declarative_base
Base = declarative_base()
class Item(Base):
__tablename__ = "items"
id = Column(Integer, primary_key=True, index=True)
name = Column(String, index=True, nullable=False)
price = Column(Integer, default=0)
in_stock = Column(Boolean, default=True)
# create tables (for dev; use Alembic migrations in prod)
Base.metadata.create_all(bind=engine)Datensatz erzeugen
add() stützt eine neue Zeile, commit() schreibt sie in die DB, und refresh() lädt die Instanz mit servergenerierten Werten neu (wie die auto-increment id). Mehrere Schreibvorgänge in eine Transaktion wickeln und einmal am Ende committen.
from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session
app = FastAPI()
@app.post("/items", status_code=201)
def create_item(payload: ItemCreate, db: Session = Depends(get_db)):
item = Item(name=payload.name, price=payload.price)
db.add(item)
db.commit()
db.refresh(item) # load generated id
return itemDatensätze abfragen
db.query(Model) startet eine Abfrage; .filter() wendet WHERE-Bedingungen an, .offset()/.limit() paginieren, .first() gibt eine Zeile oder None zurück, .all() eine Liste. .filter_by(name=x) für einfache Gleichheits-Bedingungen.
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session
app = FastAPI()
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, db: Session = Depends(get_db)):
return db.query(Item).offset(skip).limit(limit).all()
@app.get("/items/{item_id}")
def get_item(item_id: int, db: Session = Depends(get_db)):
item = db.query(Item).filter(Item.id == item_id).first()
if not item:
raise HTTPException(status_code=404, detail="not found")
return itemUpdate & Delete
Für Teilupdates über model_dump(exclude_unset=True) iterieren, sodass nur gelieferte Felder ändern. delete() stützt die Entfernung; commit() finalisiert. Bei DELETE-Erfolg 204 No Content zurückgeben.
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session
app = FastAPI()
@app.put("/items/{item_id}")
def update_item(item_id: int, payload: ItemUpdate, db: Session = Depends(get_db)):
item = db.query(Item).filter(Item.id == item_id).first()
if not item:
raise HTTPException(status_code=404, detail="not found")
for k, v in payload.model_dump(exclude_unset=True).items():
setattr(item, k, v)
db.commit()
db.refresh(item)
return item
@app.delete("/items/{item_id}", status_code=204)
def delete_item(item_id: int, db: Session = Depends(get_db)):
item = db.query(Item).filter(Item.id == item_id).first()
if item:
db.delete(item)
db.commit()Datenbank (Tortoise ORM)
Tortoise-Setup
Tortoise ORM ist async-nativ und passt gut zu FastAPI. Beim Startup mit db_url und dem/den Modul(n) mit deinen Models initialisieren. generate_schemas() ist für Dev okay; in Produktion Aerich für Migrationen. In neuem Code den lifespan-Handler statt on_event verwenden.
from fastapi import FastAPI
from tortoise import Tortoise
app = FastAPI()
async def init():
await Tortoise.init(
db_url="sqlite://db.sqlite3",
modules={"models": ["app.models"]},
)
await Tortoise.generate_schemas()
@app.on_event("startup")
async def startup():
await init()
@app.on_event("shutdown")
async def shutdown():
await Tortoise.close_connections()Model-Definition
Tortoise-Models erben von Model und deklarieren Felder über tortoise.fields. Feldtypen mappen auf DB-Spaltentypen. Tabellennamen in der inneren Meta-Klasse setzen. Beziehungen nutzen ForeignKeyField, ManyToManyField usw.
from tortoise import fields
from tortoise.models import Model
class Item(Model):
id = fields.IntField(pk=True)
name = fields.CharField(max_length=100)
price = fields.FloatField(default=0.0)
created_at = fields.DatetimeField(auto_now_add=True)
class Meta:
table = "items"
def __str__(self):
return self.nameDatensatz erzeugen
Item.create() ist eine Coroutine, die einfügt und die neue Zeile zurückgibt. Für eine Pydantic-Antwort ein BaseModel mit from_tortoise_orm() bauen (über tortoise.contrib.pydantic), damit Tortoise async geladene Relationen korrekt serialisiert.
from fastapi import FastAPI
from pydantic import BaseModel
from .models import Item
app = FastAPI()
class ItemIn(BaseModel):
name: str
price: float
@app.post("/items", response_model=ItemOut, status_code=201)
async def create_item(payload: ItemIn):
item = await Item.create(name=payload.name, price=payload.price)
return await ItemOut.from_tortoise_orm(item)Async-Abfrage
Tortoise-Abfragen werden awaited: .all() gibt ein queryset zurück, .filter() ergänzt Bedingungen, .get_or_none() holt eine Zeile oder None, .first() den ersten Treffer. .get() vermeiden, außer man erwartet genau eine Zeile (wirft, wenn nicht gefunden).
from fastapi import FastAPI, HTTPException
from .models import Item
app = FastAPI()
@app.get("/items")
async def list_items(skip: int = 0, limit: int = 10):
return await Item.all().offset(skip).limit(limit)
@app.get("/items/{item_id}")
async def get_item(item_id: int):
item = await Item.get_or_none(id=item_id)
if not item:
raise HTTPException(status_code=404, detail="not found")
return itemUpdate & Delete
Model-Attribute ändern, dann await save() zum Aktualisieren einer Zeile, oder await Item.filter(id=...).update(name=x) für Bulk-Updates. await item.delete() entfernt die Zeile. Jede Methode ist eine Coroutine und muss awaited werden.
from fastapi import FastAPI, HTTPException
from .models import Item
app = FastAPI()
@app.put("/items/{item_id}")
async def update_item(item_id: int, name: str):
item = await Item.get_or_none(id=item_id)
if not item:
raise HTTPException(status_code=404, detail="not found")
item.name = name
await item.save()
return item
@app.delete("/items/{item_id}", status_code=204)
async def delete_item(item_id: int):
item = await Item.get_or_none(id=item_id)
if item:
await item.delete()Tortoise-Pydantic-Schemas
tortoise.contrib.pydantic generiert Pydantic-Models direkt aus Tortoise-Models, sodass man nicht zwei Schemas pflegt. pydantic_model_creator für ein einzelnes Objekt, pydantic_queryset_creator für eine Listen-Antwort.
from tortoise.contrib.pydantic import pydantic_model_creator, pydantic_queryset_creator
from .models import Item
ItemOut = pydantic_model_creator(Item, name="ItemOut")
ItemList = pydantic_queryset_creator(Item)
@app.get("/items", response_model=ItemList)
async def list_items():
return await Item.all()
# auto-generates a Pydantic model from the Tortoise model,
# including types and docstrings.Testen (TestClient)
TestClient-Grundlagen
TestClient umwickelt deine App und erlaubt Anfragen im Prozess (kein echter Socket). Basiert auf httpx und funktioniert out of the box mit pytest. Denselben App-Instance importieren, den du in Produktion betreibst.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_root():
response = client.get("/")
assert response.status_code == 200
assert response.json() == {"Hello": "World"}
# TestClient is based on httpx; no network is involved —
# it calls the ASGI app directly in-process.GET & POST testen
json= für JSON-Bodies, params= für Query-Params, headers= für Header und files= für multipart-Uploads übergeben. Validierungs-Fehler geben 422 — auf status_code und die Struktur des Fehler-'detail' assertionen.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_create_item():
response = client.post(
"/items",
json={"name": "Apple", "price": 0.5},
)
assert response.status_code == 201
assert response.json()["name"] == "Apple"
def test_validation_error():
response = client.post("/items", json={"name": "Apple"}) # missing price
assert response.status_code == 422Pytest-Fixture
Eine pytest-Fixture, die einen TestClient zurückgibt, hält Tests DRY und gibt jedem Test einen frischen Client. Für DB-basierte Tests eine Fixture ergänzen, die Tabellen erzeugt/droppt oder pro Test einen Transaktions-Rollback nutzt, um sie zu isolieren.
import pytest
from fastapi.testclient import TestClient
from main import app
@pytest.fixture
def client():
return TestClient(app)
def test_read(client):
r = client.get("/items")
assert r.status_code == 200
def test_create(client):
r = client.post("/items", json={"name": "X"})
assert r.status_code == 201
# run: pytest -vDependencies überschreiben
app.dependency_overrides tauscht eine Dependency (etwa die echte DB-Session oder Auth) während der Tests gegen ein Mock/Fake, ohne die Routen zu ändern. Der kanonische Weg, Endpunkte isoliert von externen Diensten zu testen. Nach den Tests leeren.
from fastapi.testclient import TestClient
from main import app, get_db
def get_test_db():
# return a test session or mock
yield FakeSession()
app.dependency_overrides[get_db] = get_test_db
client = TestClient(app)
def test_items():
r = client.get("/items")
assert r.status_code == 200
# restore afterwards:
app.dependency_overrides.clear()Authentifizierung testen
OAuth2PasswordRequestForm erwartet form-kodierte Daten (data=, nicht json=). Den zurückgegebenen Token im Authorization: Bearer-Header für nachfolgende geschützte Anfragen verwenden. Um Auth ganz zu umgehen, stattdessen die get_current_user-Dependency überschreiben.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def get_token():
r = client.post(
"/token",
data={"username": "admin", "password": "secret"},
)
return r.json()["access_token"]
def test_protected():
token = get_token()
r = client.get(
"/me",
headers={"Authorization": f"Bearer {token}"},
)
assert r.status_code == 200
assert r.json()["username"] == "admin"WebSocket testen
TestClient.websocket_connect() öffnet einen WebSocket innerhalb eines Context-Managers. send_text/receive_text (und die json/bytes-Varianten) zum Austausch von Nachrichten. Empfangen auf einer geschlossenen Verbindung wirft WebSocketDisconnect.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_websocket():
with client.websocket_connect("/ws") as ws:
ws.send_text("hello")
data = ws.receive_text()
assert data == "echo: hello"
def test_websocket_close():
with client.websocket_connect("/ws") as ws:
ws.send_text("quit")
# the server closes the connectionOpenAPI-Docs
Swagger UI
FastAPI generiert automatisch eine interaktive Swagger UI unter /docs aus deinen Routen, Typen und Docstrings. title/description/version an der App setzen und pro Route einen Docstring oder summary/description ergänzen, um die UI anzureichern.
from fastapi import FastAPI
app = FastAPI(
title="My API",
description="Sample API with auto docs",
version="1.0.0",
)
@app.get("/items", summary="List items", description="Returns all items")
def list_items():
"""Get every item in the catalog."""
return [{"id": 1}]
# interactive docs at: http://localhost:8000/docsReDoc
ReDoc unter /redoc ist eine read-only, dokumentationsfokussierte Alternative zu Swagger. Das rohe OpenAPI-Schema liegt unter /openapi.json und lässt sich anderen Tools füttern. Docs abschalten mit docs_url=None, redoc_url=None, openapi_url=None (z. B. in Produktion).
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def root():
return {"hello": "world"}
# ReDoc (alternative docs UI) at: http://localhost:8000/redoc
# raw OpenAPI JSON at: http://localhost:8000/openapi.json
# disable docs entirely:
# app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)Tags & Gruppierung
Tags gruppieren Routen in der Docs-UI. Tag-Metadaten (name, description, externalDocs) vorab in openapi_tags deklarieren, damit die Gruppe schon erscheint, bevor eine Route sie nutzt. deprecated=True markiert einen Endpunkt in den Docs als veraltet.
from fastapi import FastAPI
app = FastAPI(openapi_tags=[
{"name": "users", "description": "User management"},
{"name": "items", "description": "Item operations"},
])
@app.get("/users", tags=["users"])
def list_users(): ...
@app.post("/items", tags=["items"])
def create_item(): ...
@app.get("/items/{id}", tags=["items"], deprecated=True)
def get_item(id: int): ...Routen-Metadaten
Decoratoren akzeptieren Metadaten, die in OpenAPI fließen: summary (kurzer Titel), description (langer Text), response_description, tags, deprecated und status_code. Ein Docstring wird als description genutzt, wenn nicht explizit einer übergeben wird.
from fastapi import FastAPI, status
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
app = FastAPI()
@app.post(
"/items",
response_model=Item,
status_code=status.HTTP_201_CREATED,
summary="Create an item",
description="Creates a new item and returns it.",
tags=["items"],
response_description="The created item",
)
def create_item(item: Item):
"""Create endpoint docstring — also shown in docs."""
return itemFeld-Beispiele
Field(examples=[...]) und Body(examples=[...]) ergänzen Beispiel-Payloads zur Swagger-UI-'Try it out' und der Beispiele-Dropdown. Body-Beispiele können mehrere Fälle mit summaries enthalten, um gültige und ungültige Inputs zu zeigen.
from pydantic import BaseModel, Field
from fastapi import FastAPI, Body
class Item(BaseModel):
name: str = Field(examples=["Apple"])
price: float = Field(examples=[0.5], gt=0)
app = FastAPI()
@app.post("/items")
def create_item(item: Item):
return item
@app.post("/manual")
def manual(
item: Item = Body(
examples=[
{"summary": "valid", "value": {"name": "Apple", "price": 0.5}},
{"summary": "invalid", "value": {"name": "Apple", "price": -1}},
],
),
):
return itemEigenes OpenAPI-Schema
app.openapi überschreiben, um das generierte Schema anzupassen — ein Logo, extra Metadaten oder Operationen entfernen/transformieren. Das Ergebnis in app.openapi_schema cachen, damit es nur einmal erzeugt wird. Das Schema ist das, was /openapi.json ausliefert.
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI()
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
schema = get_openapi(
title="Custom API",
version="2.0.0",
routes=app.routes,
)
schema["info"]["x-logo"] = {"url": "https://example.com/logo.png"}
app.openapi_schema = schema
return schema
app.openapi = custom_openapiDeployment (Uvicorn / Gunicorn)
Uvicorn in Produktion
In Produktion Uvicorn hinter einem Reverse-Proxy (Nginx, Caddy, Cloud-Load-Balancer) betreiben. --proxy-headers verwenden, damit die App die echte Client-IP/Host aus X-Forwarded-For/X-Forwarded-Proto sieht. --reload in Produktion vermeiden.
# Run directly with uvicorn (single worker)
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1
# Recommended: behind a reverse proxy (nginx) on port 8000
# Use --proxy-headers so X-Forwarded-* is trusted
uvicorn main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips='*'Gunicorn mit Uvicorn-Workern
Gunicorn verwaltet mehrere Uvicorn-Worker-Prozesse und bringt graceful reloads, Neustarts bei Crash und Pre-Fork-Skalierung. Die UvicornWorker-Klasse verwenden. workers auf (2 * CPU-Kerne + 1) als Startpunkt setzen, dann benchmarken.
# install the uvicorn worker class
pip install "uvicorn[standard]" gunicorn
# run 4 worker processes managed by gunicorn
gunicorn main:app \
-w 4 \
-k uvicorn.workers.UvicornWorker \
-b 0.0.0.0:8000 \
--timeout 120
# -w workers (commonly 2*CPU+1), -k worker classDocker-Deployment
Ein schlankes Python-Basis-Image hält das Image klein. Abhängigkeiten vor dem Kopieren des Codes installieren, um Docker's Layer-Cache zu nutzen. Im Container mit gunicorn+uvicorn workern laufen lassen und Port 8000 zum Host oder Orchestrator exponieren.
# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["gunicorn", "main:app", "-w", "4", \
"-k", "uvicorn.workers.UvicornWorker", \
"-b", "0.0.0.0:8000"]
# build & run:
# docker build -t myapi .
# docker run -p 8000:8000 myapiUmgebungs-Konfiguration
pydantic-settings (ehemals pydantic.BaseSettings) lädt Konfiguration aus Umgebungsvariablen und .env-Dateien mit Typvalidierung. So läuft dasselbe Image in verschiedenen Umgebungen (dev/staging/prod), allein durch geänderte Env-Variablen.
import os
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
database_url: str = "sqlite:///./app.db"
secret_key: str = "change-me"
debug: bool = False
allowed_origins: list[str] = ["http://localhost:3000"]
class Config:
env_file = ".env"
env_file_encoding = "utf-8"
settings = Settings()
# .env file:
# DATABASE_URL=postgresql://user:pass@db:5432/app
# SECRET_KEY=long-random-string
# DEBUG=falseNginx-Reverse-Proxy
Nginx terminiert HTTP(S) und leitet an Uvicorn auf localhost:8000 weiter. Die X-Forwarded-*-Header setzen (und --proxy-headers auf Uvicorn), damit die App die echte Client-IP und das Schema sieht. Die Upgrade/Connection-Zeilen ermöglichen WebSocket-Support.
# /etc/nginx/conf.d/api.conf
server {
listen 80;
server_name api.example.com;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade \$http_upgrade;
proxy_set_header Connection "upgrade";
}
}Skalierung & Nebenläufigkeit
Zwei Wege skalieren: mehr Uvicorn-Worker-Prozesse pro Maschine (CPU-gebunden) und mehr Maschinen hinter einem Load Balancer (horizontal). Bei Async-Apps übernimmt die Event-Loop viele gleichzeitige I/O-Anfragen pro Worker. Einen /health-Endpunkt ergänzen, damit Orchestratoren (k8s, ECS) Liveness prüfen können.
# Workers = process count (vertical scaling); pick ~2*CPU
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
# Inside async app: concurrency is cooperative via the event loop.
# CPU-bound work blocks it — offload to a threadpool or task queue.
# Horizontal scaling: run several containers behind a load balancer.
# Use a shared store (Redis) for session state and rate limits.
# Health check endpoint for the balancer:
@app.get("/health")
def health():
return {"status": "ok"}Fortgeschrittene Themen
Lifespan-Events
Der lifespan-Kontextmanager ersetzt die veralteten on_event('startup'/'shutdown')-Handler. Code vor yield läuft beim Start; Code nach yield beim Herunterfahren, selbst wenn der Start scheitert. Damit DB-Verbindungen, ML-Models und Caches initialisieren.
from contextlib import asynccontextmanager
from fastapi import FastAPI
@asynccontextmanager
async def lifespan(app: FastAPI):
# runs at startup
print("starting up")
app.state.cache = {}
yield
# runs at shutdown
print("shutting down")
await app.state.cache.clear()
app = FastAPI(lifespan=lifespan)
# the old @app.on_event("startup") / "shutdown" are deprecated
# in favor of the lifespan handler above.Sub-Applications (Mount)
app.mount() hängt eine Sub-Application unter ein Pfad-Präfix — nützlich für versionierte APIs oder das Kombinieren mehrerer Apps. Jede Sub-App hat eigene Routen und ein eigenes OpenAPI-Schema; die Docs des Parents enthalten die Routen des Kindes standardmäßig nicht.
from fastapi import FastAPI
app = FastAPI()
api_v1 = FastAPI()
api_v2 = FastAPI()
@api_v1.get("/items")
def v1_items():
return {"version": 1}
@api_v2.get("/items")
def v2_items():
return {"version": 2}
app.mount("/v1", api_v1)
app.mount("/v2", api_v2)
# GET /v1/items -> {"version": 1}
# GET /v2/items -> {"version": 2}APIRouter
APIRouter gruppiert zugehörige Routen zu einem Modul mit geteiltem prefix, tags, dependencies und responses. Einbinden über app.include_router(router) (optional mit eigenem prefix oder tags). Das Standardmuster für strukturierte, nicht-triviale Apps.
from fastapi import APIRouter, Depends
router = APIRouter(
prefix="/items",
tags=["items"],
dependencies=[Depends(verify_token)],
responses={404: {"description": "Not found"}},
)
@router.get("/")
def list_items():
return []
@router.get("/{item_id}")
def get_item(item_id: int):
return {"id": item_id}
# in main.py: app.include_router(router)Statische Dateien
StaticFiles liefert ein Verzeichnis statischer Assets (Bilder, CSS, JS) unter einem URL-Präfix aus. Pro Verzeichnis einmal mounten. Für SPA-Frontends eine abschließende catch-all-Route mounten, die auf index.html zeigt. Statische Dateien umgehen das Routing-System aus Geschwindigkeitsgründen.
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
app = FastAPI()
# serve files from ./static at /static
app.mount("/static", StaticFiles(directory="static"), name="static")
# /static/logo.png -> ./static/logo.png
# /static/css/app.css -> ./static/css/app.cssStreaming-Response
StreamingResponse sendet eine Antwort, die in Chunks (Generator/Iterator) erzeugt wird, statt den ganzen Body im Speicher aufzubauen — ideal für große CSV-Exporte, File-Streaming oder SSE. media_type passend setzen, damit Clients den Stream korrekt behandeln.
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import csv, io
app = FastAPI()
def iter_csv():
output = io.StringIO()
writer = csv.writer(output)
writer.writerow(["id", "name"])
for i in range(1000):
writer.writerow([i, f"name-{i}"])
yield output.getvalue()
output.seek(0)
output.truncate(0)
@app.get("/export.csv")
def export():
return StreamingResponse(
iter_csv(),
media_type="text/csv",
headers={"Content-Disposition": "attachment; filename=export.csv"},
)Eigene Route-Klasse
APIRoute abzuleiten erlaubt, jeden Route-Handler mit eigener Logik (Logging, Tracing, Timing) zu umwickeln, ohne jeden Endpunkt anzufassen. app.router.route_class setzen oder route_class an APIRouter übergeben. Der Handler läuft für jede passende Anfrage.
from fastapi import FastAPI, Request, Response
from fastapi.routing import APIRoute
from typing import Callable
class LoggingRoute(APIRoute):
def get_route_handler(self) -> Callable:
original = super().get_route_handler()
async def handler(request: Request) -> Response:
print(f"-> {request.method} {request.url.path}")
response = await original(request)
print(f"<- {response.status_code}")
return response
return handler
app = FastAPI()
app.router.route_class = LoggingRoute
@app.get("/items")
def items():
return {"items": []}Verwandte FastAPI-Snippets
Copy-paste ready code for common tasks.
Path Parameters
Capture typed path segments with validation.
Query Parameters
Parse query strings with defaults and validation.
Pydantic Request Body
Validate JSON bodies with Pydantic models.
Dependency Injection
Share logic via Depends and yield-based dependencies.
Response Model
Shape and filter responses with response_model.
JWT Auth
Issue and verify JSON Web Tokens with OAuth2.
Async and Await
Define async handlers and run blocking work in a thread.
Middleware
Add CORS, timing, and custom middleware.
Was this helpful?