FastAPI obsługuje błędy poprzez zgłaszanie wyjątków, które konwertuje w właściwe odpowiedzi HTTP. HTTPException obejmuje większość przypadków; niestandardowe handlery wyjątków pozwalają kontrolować formatowanie błędów globalnie.
fastapi HTTPException
():
item = db.get()
item:
HTTPException(status_code=, detail=)
item.is_public:
HTTPException(status_code=, detail=)
item
raise HTTPException(status_code=..., detail=...) to idiomatyczny sposób na zwrócenie błędu — FastAPI tworzy odpowiedź JSON {"detail": "..."} z podanym statusem. detail może być dowolną wartością serializowalną do JSON (string, dict, lista).
When request data fails Pydantic validation, FastAPI AUTOMATICALLY returns a 422
with a structured list of exactly which fields are wrong — you write nothing.
from fastapi import Request
from fastapi.responses import JSONResponse
class ItemNotFound(Exception):
def __init__(self, item_id: int): self.item_id = item_id
@app.exception_handler(ItemNotFound) # handle a custom exception type globally
def handle_not_found(request: Request, exc: ItemNotFound):
return JSONResponse(status_code=404, content={"error": f"Item {exc.item_id} not found"})
@app.get("/items/{id}")
def get(id: int):
raise ItemNotFound(id) # raise your domain exception; the handler formats it
Niestandardowe handlery wyjątków pozwalają mapować twoje własne wyjątki (domenowe) na odpowiedzi, centralizując formatowanie błędów i utrzymując kod handlera czystym.
from fastapi.exceptions import RequestValidationError
@app.exception_handler(RequestValidationError) # customize the 422 validation-error format
def validation_handler(request, exc):
return JSONResponse(status_code=422, content={"errors": exc.errors()})
Poprawna obsługa błędów jest niezbędna do budowania niezawodnych, profesjonalnych API, a podejście FastAPI jest czyste i spójne.
Idiomatyczne HTTPException ułatwia zwrócenie poprawnych odpowiedzi błędów z odpowiednimi kodami statusu i wiadomościami — fundamental dla każdego endpointu, który może się nie powieść (nie znaleziono, zabronione, zły stan).
Również cenne jest to, że błędy walidacji są obsługiwane automatycznie (niepowodzenia Pydantic produkują ustrukturyzowane odpowiedzi 422 bez kodu od ciebie), i że niestandardowe handlery wyjątków pozwalają mapować twoje własne wyjątki domenowe na odpowiedzi i egzekwować spójny format błędów w całym API — poprawiając zarówno łatwość utrzymania (scentralizowana logika błędów), jak i doświadczenie klienta (przewidywalne kształty błędów).
Zrozumienie HTTPException, automatycznych błędów walidacji i niestandardowych handlerów obejmuje praktyczne spektrum obsługi błędów, czyniąc to ważną wiedzą do budowania solidnych API.