你如何处理错误和抛出 HTTP 异常？

Question

你如何处理错误和抛出 HTTP 异常？

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 的重要知识。