Unashughulikiaje hitilafu na kuinua HTTP exceptions?

Question

Accepted Answer

FastAPI hushughulikia hitilafu kwa **kuinua exceptions** ambazo huzibadilisha kuwa majibu sahihi ya HTTP. `HTTPException` hushughulikia hali nyingi; custom exception handlers hukuruhusu kudhibiti uundaji wa hitilafu kimataifa.

## Kuinua HTTPException

```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=...)` ndiyo njia ya kawaida ya kurudisha hitilafu — FastAPI huzalisha jibu la JSON `{"detail": "..."}` na hadhi (status) iliyotolewa. `detail` inaweza kuwa thamani yoyote inayoweza kubadilishwa kuwa JSON (string, dict, list).

## Hitilafu za uthibitishaji ni za kiotomatiki (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.
```

## Custom exception handlers (uundaji wa kimataifa)

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

Custom exception handlers hukuruhusu kuoanisha exceptions zako mwenyewe (za kikoa) na majibu, kuweka uundaji wa hitilafu katikati na kuweka msimbo wa handler safi.

## Kubadilisha default handlers

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

## Kwa nini ni muhimu

Ushughulikiaji sahihi wa hitilafu ni wa lazima kwa kujenga API za kuaminika na za kitaalamu, na mbinu ya FastAPI ni safi na thabiti.

`HTTPException` ya kawaida hurahisisha kurudisha majibu sahihi ya hitilafu yenye status codes na ujumbe unaofaa — jambo la msingi kwa endpoint yoyote inayoweza kushindwa (haijapatikana, imekatazwa, hali mbaya).

Jambo la thamani sawa ni kwamba **hitilafu za uthibitishaji hushughulikiwa kiotomatiki** (kushindwa kwa Pydantic huzalisha majibu 422 yaliyopangwa bila msimbo wowote kutoka kwako), na kwamba **custom exception handlers** hukuruhusu kuoanisha exceptions zako za kikoa na majibu na kutekeleza muundo thabiti wa hitilafu katika API nzima — kuboresha udumishaji (mantiki ya hitilafu iliyowekwa katikati) na uzoefu wa mteja (maumbo ya hitilafu yanayotabirika).

Kuelewa `HTTPException`, hitilafu za kiotomatiki za uthibitishaji, na custom handlers hushughulikia wigo wa vitendo wa ushughulikiaji wa hitilafu, jambo linalofanya haya kuwa maarifa muhimu ya kujenga API imara.