fastapi 如何让错误响应统一使用自定义异常模型-Python教程-PHP中文网

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

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

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

定义统一的错误响应模型

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

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

创建自定义异常类

继承 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
<p>@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()
)</p>

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

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

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

Python 环境工具专业版

Python 环境工具专业版功能概述Python 环境工具专业版是一项面向实际任务的技能。它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。核心要点使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。执行完成后建议检查结果是否符合预期，并保留必要记录。使用与执行同时注意输入完整性、执行条件和输出可用性。从功能定位来看，该技能

下载

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if 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} 不存在"
        )
<h1>使用时</h1><p>raise NotFoundException("用户")</p>

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