13 FastAPI异常处理机制

最新推荐文章于 2025-05-19 21:05:06 发布

安迪小宝

最新推荐文章于 2025-05-19 21:05:06 发布

阅读量991

点赞数 20

分类专栏： python FastAPI 文章标签： fastapi

本文链接：https://blog.youkuaiyun.com/wujianyouhun/article/details/145584065

版权

python 同时被 2 个专栏收录

58 篇文章

订阅专栏

FastAPI

18 篇文章

订阅专栏

在构建现代 Web API 时，错误处理和异常管理是一个关键的部分，尤其是在用户体验和系统可靠性方面。FastAPI 提供了一套强大且灵活的错误处理机制，允许开发者返回合适的错误响应并进行定制，从而提供更友好的错误信息。

本文将介绍如何在 FastAPI 中处理错误和异常，具体包括：

使用 HTTPException 返回错误响应
定制异常处理器
捕获并处理不同类型的异常

1. 异常处理机制

1.1 使用 `HTTPException` 返回错误响应

在 FastAPI 中，最常见的错误处理方式是通过 HTTPException 返回错误响应。HTTPException 是 FastAPI 中用于抛出 HTTP 错误的主要方式，它允许你指定错误的状态码、错误详情和其他信息。

1.1.1 基本用法

你可以在视图函数中使用 HTTPException 来返回错误响应。例如，当请求数据无效时，可以返回 400 错误：

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=400, detail="Item ID must be greater than 0")
    return {"item_id": item_id}

在上面的代码中，当 item_id 小于 1 时，我们通过 HTTPException 抛出一个 400 错误，并提供详细的错误信息 Item ID must be greater than 0。这样，客户端在访问时会得到一个清晰的错误响应。

1.1.2 设置更多的错误信息

HTTPException 不仅可以设置状态码和错误详情，还可以通过 headers 参数自定义返回的 HTTP 头：

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id < 1:
        raise HTTPException(
            status_code=400,
            detail="Item ID must be greater than 0",
            headers={"X-Error": "Item ID validation failed"}
        )
    return {"item_id": item_id}

在这个例子中，我们添加了一个名为 X-Error 的自定义头部，帮助客户端了解更多关于错误的上下文信息。

1.2 捕获并处理不同类型的异常

除了 HTTPException，FastAPI 还支持捕获和处理多种不同类型的异常。例如，我们可以捕获数据库连接错误、文件处理错误等，提供适当的错误响应。

from fastapi import HTTPException

@app.get("/read-file/{file_path}")
async def read_file(file_path: str):
    try:
        with open(file_path, "r") as f:
            data = f.read()
        return {"content": data}
    except FileNotFoundError:
        raise HTTPException(status_code=404, detail="File not found")
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

在这个示例中，我们捕获了 FileNotFoundError 和其他异常，分别返回 404 和 500 错误。如果文件不存在，会返回“File not found”消息，而其他错误则会返回相应的异常消息。

2. 定制异常处理器

虽然使用 HTTPException 可以处理大多数常见的错误，FastAPI 还允许开发者自定义异常处理器。通过自定义异常处理器，我们可以捕获特定类型的异常并返回自定义格式的响应。

2.1 定义异常处理器

FastAPI 允许你为应用注册自定义异常处理器。这可以让你为特定的异常类型提供统一的错误响应格式。例如，我们可以定义一个处理 ValidationError（验证错误）的异常处理器，来确保返回一致的错误格式。

from fastapi import FastAPI
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
from pydantic import BaseModel, ValidationError

app = FastAPI()

# 定义异常处理器
@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request, exc: RequestValidationError):
    return JSONResponse(
        status_code=422,
        content={"message": "Validation error", "errors": exc.errors()},
    )

class Item(BaseModel):
    name: str
    price: float

@app.post("/items/")
async def create_item(item: Item):
    return {"item_name": item.name, "item_price": item.price}

在这个例子中，我们创建了一个 validation_exception_handler，它会捕获 RequestValidationError，并返回一个统一格式的错误响应。在返回的 JSON 中，我们包含了 message 和 errors 字段，帮助开发者或客户端理解验证错误的具体细节。

2.2 定制异常响应格式

在异常处理器中，你可以自由定制响应格式，确保错误信息对终端用户或开发者来说更具可读性。例如，可以返回更详细的堆栈跟踪信息或用户友好的错误提示：

@app.exception_handler(Exception)
async def general_exception_handler(request, exc: Exception):
    return JSONResponse(
        status_code=500,
        content={"message": "Internal server error", "details": str(exc)},
    )

在这个示例中，任何未经处理的异常都会被 general_exception_handler 捕获，并返回一个带有错误详情的 500 响应。这样，开发者可以在响应中查看异常的具体信息，而用户则可以得到一个更友好的错误提示。

2.3 异常处理器的注册

你可以在 FastAPI 应用实例中通过 app.add_exception_handler 来注册多个异常处理器。以下是如何注册一个处理 HTTPException 的异常处理器：

from fastapi import HTTPException

@app.exception_handler(HTTPException)
async def http_exception_handler(request, exc: HTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={"message": exc.detail},
    )

在上面的代码中，我们注册了一个处理 HTTPException 的处理器。当 HTTPException 被抛出时，它会返回自定义的错误响应格式。

3. 捕获并处理不同类型的异常

在 FastAPI 中，你不仅可以捕获和处理 HTTPException，还可以捕获所有其他类型的异常。以下是一些常见的异常类型及其处理方式：

3.1 捕获数据库连接错误

假设我们有一个数据库查询功能，当数据库连接失败时，我们可以捕获相关异常并返回适当的错误响应。

from sqlalchemy.exc import SQLAlchemyError
from fastapi import HTTPException

@app.get("/data/{item_id}")
async def get_data(item_id: int):
    try:
        data = db.query(Item).filter(Item.id == item_id).first()
        if not data:
            raise HTTPException(status_code=404, detail="Item not found")
        return data
    except SQLAlchemyError:
        raise HTTPException(status_code=500, detail="Database connection error")

3.2 捕获文件处理错误

在处理文件时，可能会遇到文件权限错误或其他问题，这时我们可以捕获异常并返回相应的错误消息：

@app.get("/upload/{filename}")
async def upload_file(filename: str):
    try:
        with open(filename, "rb") as file:
            # 处理文件
            return {"message": "File uploaded successfully"}
    except PermissionError:
        raise HTTPException(status_code=403, detail="Permission denied")
    except FileNotFoundError:
        raise HTTPException(status_code=404, detail="File not found")

3.3 捕获外部 API 调用错误

如果你在 FastAPI 应用中进行外部 API 调用，可能会遇到请求超时、服务不可用等错误。你可以通过捕获异常来处理这些情况。

import httpx

@app.get("/external-api")
async def call_external_api():
    try:
        async with httpx.AsyncClient() as client:
            response = await client.get("https://external-api.com/data")
        return response.json()
    except httpx.RequestError as e:
        raise HTTPException(status_code=500, detail=f"Error while calling external API: {e}")