FastAPI自定义异常：统一错误响应格式

FastAPI自定义异常：统一错误响应格式

【免费下载链接】fastapi-tips FastAPI Tips by The FastAPI Expert! 项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi-tips

你是否遇到过FastAPI接口返回的错误格式杂乱无章？不同异常返回不同结构，前端处理起来十分麻烦？本文将介绍如何在FastAPI项目中实现统一的错误响应格式，让你的API更加专业和易用。

读完本文，你将学会：

• 如何自定义异常类
• 如何全局捕获并处理异常
• 如何返回统一格式的错误响应
• 如何在依赖项中使用自定义异常

为什么需要统一错误响应格式

在开发API时，统一的错误响应格式能带来很多好处：

• 前端可以使用统一的逻辑处理所有错误
• 错误信息更加规范，便于调试和监控
• 提高API的专业性和易用性

自定义异常类

首先，我们需要创建自定义的异常类，用于区分不同类型的错误。

from fastapi import HTTPException
from pydantic import BaseModel

class APIException(HTTPException):
    """Base exception for API errors"""
    status_code: int
    code: str
    message: str
    
    def __init__(self, status_code: int, code: str, message: str):
        super().__init__(status_code=status_code, detail=message)
        self.code = code
        self.message = message

class ResourceNotFoundError(APIException):
    """Raised when requested resource is not found"""
    def __init__(self, resource: str, id: str):
        super().__init__(
            status_code=404,
            code="RESOURCE_NOT_FOUND",
            message=f"{resource} with id {id} not found"
        )

class ValidationError(APIException):
    """Raised when input validation fails"""
    def __init__(self, message: str):
        super().__init__(
            status_code=400,
            code="VALIDATION_ERROR",
            message=message
        )

统一错误响应模型

接下来，我们定义统一的错误响应模型，确保所有错误都遵循相同的格式。

from pydantic import BaseModel
from typing import Optional, Any

class ErrorResponse(BaseModel):
    """Unified error response format"""
    success: bool = False
    code: str
    message: str
    details: Optional[Any] = None

全局异常处理器

使用FastAPI的异常处理机制，我们可以全局捕获并处理异常，返回统一格式的响应。

from fastapi import Request, FastAPI
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
from pydantic import ValidationError as PydanticValidationError

app = FastAPI()

@app.exception_handler(APIException)
async def api_exception_handler(request: Request, exc: APIException):
    """Handle custom API exceptions"""
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "success": False,
            "code": exc.code,
            "message": exc.message
        }
    )

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    """Handle FastAPI validation errors"""
    return JSONResponse(
        status_code=400,
        content={
            "success": False,
            "code": "VALIDATION_ERROR",
            "message": "Validation failed",
            "details": exc.errors()
        }
    )

@app.exception_handler(PydanticValidationError)
async def pydantic_validation_exception_handler(request: Request, exc: PydanticValidationError):
    """Handle Pydantic validation errors"""
    return JSONResponse(
        status_code=400,
        content={
            "success": False,
            "code": "VALIDATION_ERROR",
            "message": "Validation failed",
            "details": exc.errors()
        }
    )

在路由中使用自定义异常

现在我们可以在路由函数中使用自定义异常了：

from fastapi import Depends, Path
from typing import Annotated

@app.get("/items/{item_id}")
async def get_item(item_id: Annotated[int, Path(ge=1)]):
    if item_id == 42:
        raise ResourceNotFoundError("Item", item_id)
    if item_id > 100:
        raise ValidationError("Item ID must be less than 100")
    return {"success": True, "data": {"item_id": item_id}}

在依赖项中使用自定义异常

我们还可以在依赖项中使用自定义异常，如README.md中提到的依赖项可能在线程中运行：

from fastapi import Depends

async def get_current_user(user_id: str = None):
    if not user_id:
        raise ValidationError("User ID is required")
    # 实际应用中这里会有更多验证逻辑
    return {"user_id": user_id}

@app.get("/users/me")
async def read_current_user(current_user: dict = Depends(get_current_user)):
    return {"success": True, "data": current_user}

异常处理流程

以下是FastAPI处理异常的流程：

总结

通过本文的介绍，你已经学会了如何在FastAPI项目中实现统一的错误响应格式。这包括：

1. 创建自定义异常类
2. 定义统一的错误响应模型
3. 实现全局异常处理器
4. 在路由和依赖项中使用自定义异常

这种方式可以让你的API更加专业，同时也方便前端开发人员处理错误。如果你想了解更多FastAPI技巧，可以参考README.md中的其他内容。

希望这篇文章对你有所帮助！如果你有任何问题或建议，欢迎在评论区留言。

【免费下载链接】fastapi-tips FastAPI Tips by The FastAPI Expert! 项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi-tips