Как вы обрабатываете ошибки и выбрасываете HTTP-исключения?

Question

Accepted Answer

FastAPI обрабатывает ошибки, **выбрасывая исключения**, которые он преобразует в надлежащие HTTP-ответы. `HTTPException` охватывает большинство случаев; пользовательские обработчики исключений позволяют вам контролировать форматирование ошибок глобально.

## Выброс 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=...)` — идиоматичный способ вернуть ошибку — FastAPI создает JSON-ответ `{"detail": "..."}` с указанным статусом. `detail` может быть любым JSON-сериализуемым значением (строка, словарь, список).

## Ошибки валидации автоматические (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.
```

## Пользовательские обработчики исключений (глобальное форматирование)

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

Пользовательские обработчики исключений позволяют вам сопоставить ваши собственные (доменные) исключения с ответами, централизуя форматирование ошибок и поддерживая чистоту кода обработчика.

## Переопределение обработчиков по умолчанию

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

## Почему это важно

Правильная обработка ошибок является необходимым условием для создания надежных, профессиональных API, и подход FastAPI чист и последователен.

Идиоматичная `HTTPException` упрощает возврат правильных ответов об ошибках с соответствующими кодами статуса и сообщениями — это фундамент для любой конечной точки, которая может завершиться ошибкой (не найдено, запрещено, неправильное состояние).

В равной степени ценно то, что **ошибки валидации обрабатываются автоматически** (ошибки Pydantic производят структурированные 422-ответы без кода с вашей стороны), и что **пользовательские обработчики исключений** позволяют вам сопоставить ваши собственные доменные исключения с ответами и обеспечить согласованный формат ошибок во всем API — улучшая как поддерживаемость (централизованная логика ошибок), так и взаимодействие с клиентом (предсказуемые формы ошибок).

Понимание `HTTPException`, автоматических ошибок валидации и пользовательских обработчиков охватывает практический спектр обработки ошибок, что делает это важным знанием для создания надежных API.