fastapi 如何让错误响应统一使用自定义异常模型

FastAPI中统一错误响应需结合自定义异常类、@app.exception_handler()装饰器和Pydantic模型。先定义ErrorResponse模型，再创建继承Exception的APIException类，接着注册全局处理器返回JSONResponse，最后在路由中raise实例即可输出标准化错误。

fastapi 如何让错误响应统一使用自定义异常模型第1张

FastAPI 中让错误响应统一使用自定义异常模型，核心是结合 Exception 类、@app.exception_handler() 装饰器和 Pydantic 模型三者完成标准化输出。

定义统一的错误响应模型

先用 Pydantic 创建一个结构清晰的错误响应模型，例如包含状态码、错误码、消息和可选详情：

from pydantic import BaseModel
from typing import Optional
class ErrorResponse(BaseModel):
code: int
message: str
detail: Optional[str] = None

创建自定义异常类

继承 Python 的 Exception，并携带必要字段（如 status_code、code、message），方便后续处理器提取：

class APIException(Exception):
    def __init__(self, status_code: int, code: int, message: str, detail: str = None):
        self.status_code = status_code
        self.code = code
        self.message = message
        self.detail = detail

注册全局异常处理器

使用 @app.exception_handler(APIException) 拦截所有该类型异常，并返回符合 ErrorResponse 模型的 JSON 响应：

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
@app.exception_handler(APIException)
async def api_exception_handler(request: Request, exc: APIException):
return JSONResponse(
status_code=exc.status_code,
content=ErrorResponse(
code=exc.code,
message=exc.message,
detail=exc.detail
).dict()
)

注意：这个处理器只捕获 APIException 及其子类。若需统一处理所有未捕获异常（如 422 验证错误），可额外注册 RequestValidationError 或通用 Exception 处理器，但建议保持语义明确，避免掩盖开发问题。

在路由中主动抛出自定义异常

直接 raise 实例即可，FastAPI 会自动交由对应 handler 处理：

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id < 1:
        raise APIException(
            status_code=400,
            code=1001,
            message="无效的 item ID",
            detail="item_id 必须大于 0"
        )
    return {"id": item_id}

此时响应体为标准 JSON：

{
  "code": 1001,
  "message": "无效的 item ID",
  "detail": "item_id 必须大于 0"
}

状态码也正确设为 400。

进阶：支持多种错误类型（可选）

可定义不同业务异常子类，复用同一 handler：

class NotFoundException(APIException):
    def __init__(self, resource: str):
        super().__init__(
            status_code=404,
            code=2001,
            message=f"{resource} 不存在"
        )
使用时
raise NotFoundException("用户")

这样既保持统一格式，又提升代码可读性和维护性。