FastAPI 中的错误处理：如何让错误信息更有价值

开头：

下面详细介绍如何在 FastAPI 中实现有效的错误处理策略。我们将讨论使用 HTTPException 来抛出带有详细描述的错误，定义 Pydantic 模型来结构化错误响应，以及如何通过自定义异常处理器来统一处理错误。此外，我们还将展示如何利用 JSONResponse 和路由装饰器中的 responses 参数来自定义错误信息。通过这些方法，你的 API 将能够提供清晰、一致且有用的错误信息，从而提高 API 的可用性和可维护性。

在 FastAPI中，为自定义错误添加详细的错误信息可以通过以下几种方式实现：

1. 使用 HTTPException

当你想要立即返回一个错误响应时，可以直接在路由函数中抛出一个 HTTPException，并传入 detail 参数来提供详细的错误信息。

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id != 1:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item_id": item_id, "value": "Foo"}

2. 自定义响应模型

你可以定义一个 Pydantic 模型来表示错误响应的结构，并在抛出 HTTPException 时使用该模型。

from fastapi import FastAPI
from fastapi.responses import JSONResponse
from pydantic import BaseModel

class ErrorModel(BaseModel):
    error: str
    detail: str

app = FastAPI()

@app.exception_handler(HTTPException)
async def http_exception_handler(request, exc):
    return JSONResponse(
        status_code=exc.status_code,
        content=ErrorModel(error=exc.detail, detail=f"An error occurred: {exc.detail}")
    )

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id != 1:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item_id": item_id, "value": "Foo"}

3. 使用 JSONResponse

在路由函数中返回一个 JSONResponse 对象，并设置状态码和内容。

from fastapi import FastAPI
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id != 1:
        return JSONResponse(status_code=404, content={"error": "Item not found"})
    return {"item_id": item_id, "value": "Foo"}

4. 自定义异常处理器

创建一个自定义异常处理器来统一处理异常，并返回详细的错误信息。

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from fastapi.exception_handlers import http_exception_handler

app = FastAPI()

async def custom_http_exception_handler(request: Request, exc: HTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "error": exc.detail,
            "detail": "Additional information about the error can be provided here."
        }
    )

app.add_exception_handler(HTTPException, custom_http_exception_handler)

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id != 1:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item_id": item_id, "value": "Foo"}

5. 使用 responses 参数

在路由装饰器中使用 responses 参数定义自定义状态码和错误信息。

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}", responses={404: {"model": dict, "description": "Item not found"}})
async def read_item(item_id: int):
    if item_id != 1:
        return {"error": "Item not found"}
    return {"item_id": item_id, "value": "Foo"}

通过这些方法，你可以在 FastAPI 中为自定义错误添加详细的错误信息，从而提供更丰富的错误处理和更好的客户端体验。