Kuinka käsittelet virheitä ja nosit HTTP-poikkeamia?

Question

Accepted Answer

FastAPI käsittelee virheitä **heittämällä poikkeamia**, jotka se muuntaa asianmukaisiksi HTTP-vastauksiksi. `HTTPException` kattaa useimmat tapaukset; mukautetut poikkeamakäsittelijät antavat sinulle mahdollisuuden hallita virheiden muotoilua globaalisti.

## HTTPException nostaminen

```python
from fastapi import HTTPException

@app.get("/items/{id}")
def get_item(id: int):
    item = db.get(id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found")   # → 404 JSON response
    if not item.is_public:
        raise HTTPException(status_code=403, detail="Forbidden")
    return item
```

`raise HTTPException(status_code=..., detail=...)` on idiomatinen tapa palauttaa virhe — FastAPI tuottaa JSON-vastauksen `{"detail": "..."}` annetulla tilalla. `detail` voi olla mikä tahansa JSON-sarjoitettava arvo (merkkijono, dict, lista).

## Validointivirheet ovat automaattisia (422)

```text
When request data fails Pydantic validation, FastAPI AUTOMATICALLY returns a 422
with a structured list of exactly which fields are wrong — you write nothing.
```

## Mukautetut poikkeamakäsittelijät (globaali muotoilu)

```python
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
```

Mukauttavat poikkeamakäsittelijät antavat sinulle mahdollisuuden yhdistää omat (toimialueen) poikkeavat vastauksiinsa, keskittää virheiden muotoilua ja pitää käsittelijäkoodin puhtaana.

## Oletuskäsittelijöiden ohittaminen

```python
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()})
```

## Miksi se on tärkeää

Oikea virheiden käsittely on välttämätöntä luotettavien, ammattimaisten API-ohjelmointirajapintojen rakentamiseen, ja FastAPI:n lähestymistapa on puhdas ja johdonmukainen.

Idiomatinen `HTTPException` helpottaa oikeiden virheiden palauttamista asianmukaisin tilakoodein ja sanoin — perustavanlaatuinen kaikille päätepisteitä, jotka voivat epäonnistua (ei löydy, kielletty, huono tila).

Yhtä arvokas on, että **validointivirheet käsitellään automaattisesti** (Pydantic-virheet tuottavat jäsenneltyjä 422-vastauksia ilman koodia sinulta), ja että **mukautetut poikkeamakäsittelijät** antavat sinulle mahdollisuuden yhdistää omat toimialueen poikkeavat vastauksiinsa ja pakottaa yhdenmukaisen virheiden muotoilun koko API:ssa — parantaa sekä ylläpidettävyyttä (keskitetty virhelogiikka) että asiakkaan kokemusta (ennakoitavat virheiden muodot).

`HTTPException`, automaattisten validointivirheiden ja mukautettujen käsittelijöiden ymmärtäminen kattaa virheiden käsittelyn käytännön kirjon, mikä tekee siitä tärkeän tiedon kestävien API-rajapintojen rakentamiseen.