23 FastAPI 自定义异常处理

在上一篇中，我们讨论了 FastAPI 中的常见错误处理。了解了如何使用内置的异常和中间件来捕获常见错误后，接下来，我们将深入了解如何创建自定义异常处理器，以便对特定错误进行处理并返回自定义的响应。

自定义异常

首先，我们需要定义自定义异常。通过定义异常类，我们可以在 FastAPI 应用程序中捕获特定类型的错误。例如，让我们定义一个简单的 ItemNotFound 异常：

class ItemNotFound(Exception):
    def __init__(self, item_id: int):
        self.item_id = item_id

这个自定义异常类接受一个 item_id 参数，用于指明未找到的项目。

创建自定义异常处理器

接下来，我们需要为我们的自定义异常类实现一个异常处理器。FastAPI 提供了一个装饰器 app.exception_handler()，我们可以利用它来注册自定义的异常处理函数。

from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse

app = FastAPI()

@app.exception_handler(ItemNotFound)
async def item_not_found_exception_handler(request: Request, exc: ItemNotFound):
    return JSONResponse(
        status_code=404,
        content={"message": f"Item with id {exc.item_id} not found."},
    )

在上面的代码中，item_not_found_exception_handler 函数接收一个 Request 和我们的自定义异常 ItemNotFound 作为参数。我们利用 JSONResponse 返回了一个 JSON 格式的错误消息，包含了状态码和详细信息。

在路由中抛出自定义异常

现在，我们可以在路由中使用这个自定义异常。假设我们有一个简单的项目管理 API，用户可以通过 ID 获取项目，但如果项目不存在则抛出 ItemNotFound 异常：

from fastapi import Path

# 示例数据
items = {1: "item 1", 2: "item 2"}

@app.get("/items/{item_id}")
async def read_item(item_id: int = Path(..., description="The ID of the item to retrieve")):
    if item_id not in items:
        raise ItemNotFound(item_id=item_id)
    return {"item": items[item_id]}

在这个路由中，我们检查请求的 item_id 是否在示例数据 items 中。如果没有找到对应的项，我们就抛出 ItemNotFound 异常，从而触发我们之前定义的自定义异常处理器。

测试自定义异常处理

现在让我们测试这个例子。启动 FastAPI 应用程序，并尝试访问:

• 有效的 ID：GET /items/1 将返回 { "item": "item 1" }
• 无效的 ID：GET /items/3 将返回一个自定义错误响应：

{
    "message": "Item with id 3 not found."
}

小结

通过本节的学习，我们创建了一个自定义异常类 ItemNotFound，并实现了一个专门的异常处理器来返回自定义的错误响应。这种方法在处理复杂应用中的特定错误时非常有用，它让我们的 API 返回更加友好的错误信息。

接下来，在下一篇中，我们将讨论 FastAPI 中的 HTTP 异常响应，以便更好地处理和返回各种 HTTP 状态码的错误。这将与我们自定义异常处理的内容形成良好的补充。