FastAPI中的错误和异常处理指南

有效地处理错误和异常对于构建健壮且用户友好的API至关重要。FastAPI提供了一个强大且灵活的系统用于管理和自定义错误响应。本文将探讨在FastAPI中处理和自定义错误的各种方法，并提供实用的代码示例。

FastAPI 内置了处理常见 HTTP 错误的功能。例如，如果缺少必需的查询参数，FastAPI 会自动返回 422 状态码，表示无法解析的实体。

例子：解决缺少的查询参数

    from fastapi import FastAPI, Query  

    app = FastAPI()  

    # 该代码定义了一个FastAPI应用程序，并提供了一个读取items的接口，可以通过查询参数q来获取数据。

    @app.get("/items/")  
    async def read_items(q: str = Query(...)):  
        return {"q": q}

如果你请求 /items/** 并不带 **q** 参数，FastAPI 将返回一个 422 状态码（未处理的错误），并附带详细的错误详情。

您可以使用异常处理器来自定义错误回复。FastAPI 让您为特定异常定义处理程序，这些处理程序可以给出个性化的回复。

自定义异常处理器

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

    app = FastAPI()  

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

    @app.exception_handler(ItemNotFoundException)  
    async def item_not_found_exception_handler(request: Request, exc: ItemNotFoundException):  
        return JSONResponse(  
            status_code=404,  
            content={"message": f"ID 为 {exc.item_id} 的项目找不到"},  
        )  

    @app.get("/items/{item_id}")  
    async def read_item(item_id: int):  
        if item_id != 1:  
            raise ItemNotFoundException(item_id=item_id)  
        return {"item_id": item_id}

当出现 **ItemNotFoundException** 错误时，FastAPI 会使用自定义异常处理程序返回一个带有自定义错误信息的 404 错误。

FastAPI 采用 Pydantic 进行数据验证，并默认提供详细的错误信息。您可以自定义验证错误的响应，通过使用 **RequestValidationError** 异常处理器。

示例：自定义错误处理

from fastapi import FastAPI, Request  
from fastapi.exceptions import RequestValidationError  
from fastapi.responses import JSONResponse  

app = FastAPI()  

@app.exception_handler(RequestValidationError)  
async def validation_exception_handler(request: Request, exc: RequestValidationError):  
    return JSONResponse(  
        status_code=422,  
        content={"detail": exc.errors(), "body": exc.body},  
    )  

@app.post("/items/")  
async def create_item(name: str):  
    if not name:  
        raise RequestValidationError([{"loc": ["body", "name"], "msg": "名字是必填的", "type": "value_error"}])  
    return {"name": name}

此处理器会自定义验证错误响应消息，使其不仅包含验证错误，还包括请求体。

你可以创建一个全局异常处理程序来捕捉并处理所有未处理的异常，比如返回一个标准的错误响应。这有助于记录这些错误，并确保API始终按一致的格式返回错误。

示例：全局异常处理器

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

    app = FastAPI()  

    @app.exception_handler(Exception)  
    async def global_exception_handler(request: Request, exc: Exception):  
        logging.error(f"未捕获的异常: {exc}")  
        return JSONResponse(  
            status_code=500,  
            content={"message": "服务器内部错误"},  
        )  

    @app.get("/cause_error")  
    async def cause_error():  
        raise Exception("这里有一个未捕获的异常")

此全局处理程序会记录异常，并返回 500 内部服务器错误。

**HTTPException** 类可以用来触发带有自定义状态码和详细消息的 HTTP 错误。这在处理 API 端点中的特定错误情况时非常有用。

比如说：使用**HTTP异常**

from fastapi import FastAPI, HTTPException  

app = FastAPI()  

@app.get("/items/{item_id}")  
async def read_item(item_id: int):  
    if item_id == 0:  
        raise HTTPException(status_code=400, detail="无效的项目编号")  
    return {"item_id": item_id}

在这个示例中，如果 **item_id** 是 0，则会抛出一个带有自定义详情消息的 400 错误。

你可以使用FastAPI的，依赖注入系统来处理依赖中出现的错误。

例如：依赖项错误处理

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

app = FastAPI()  

class DependencyError(Exception):  
    pass  

async def dependency_function():  
    raise DependencyError("依赖出错")  

@app.exception_handler(DependencyError)  
async def 依赖异常处理器(request: Request, exc: DependencyError):  
    return JSONResponse(  
        status_code=500,  
        content={"message": str(exc)},  
    )  

@app.get("/items/")  
async def read_items(dep: str = Depends(dependency_function)):  
    return {"message": "成功"}

在这种情况下，如果 dependency_function 抛出 DependencyError，自定义的异常处理程序会处理它，并返回一个 500 状态码。

有效的错误处理和异常管理对于构建可靠的API至关重要。FastAPI提供了强大的工具来处理验证错误并自定义错误响应，全局或在特定依赖项内管理异常。通过使用这些技术，您可以确保您的FastAPI应用程序提供清晰和一致的错误消息，从而改善整体用户体验。

了解最新FastAPI动态和最佳实践！订阅我们的邮件列表，获得更多实用建议和独家内容。

赶紧订阅，让您的 FastAPI 项目更上一层楼！

感谢你读到最后， 在你离开前， 如果有任何问题或意见， 欢迎随时留言。

• 请给作者点赞并关注她！👏
• 通过关注我们 X | LinkedIn | YouTube | Discord
• 查看我们的其他平台：In Plain English | CoFeed | Differ
• 更多内容请参阅 Stackademic.com