FastAPI自定义异常处理：优雅转换Pydantic校验错误

FastAPI自定义异常处理：优雅转换Pydantic校验错误

背景需求

当使用FastAPI开发API服务时，Pydantic的自动校验异常默认会返回如下格式的422响应：

{
   
  "detail": [
    {
   
      "type": "missing",
      "loc": ["body", "user", "name"],
      "msg": "Field required",
      "input": null
    }
  ]
}

但在实际开发中我们通常需要：

1. 统一异常响应格式
2. 增加自定义错误码
3. 对敏感信息进行过滤
4. 支持多语言错误提示

---

实现方案

步骤1：创建自定义异常类

from fastapi import HTTPException

class APIException(HTTPException):
    def __init__(
        self,
        code: int = 40000,
        message: str = "请求参数错误",
        status_code: int = 400,
        **kwargs
    ):
        super().__init__(
            status_code=status_code,
            detail={
   
                "code": code,
                "message": message,
                "data": kwargs.get("data", None)
            }
        )

步骤2：捕获Pydantic校验异常

2.1 异常捕获机制原理

2.1.1 FastAPI的异常处理链

# FastAPI的异常处理流程示意图
客户端请求 -> 路由函数 -> 中间件处理 -> 参数校验 -> 业务逻辑 -> 返回响应
             ↑异常捕获点               ↑校验异常触发点
             异常处理器介入 ←─ 异常抛出

• 捕获时机：当请求参数不符合Pydantic模型定义时，框架会自动抛出RequestValidationError（HTTP 422错误）
• 处理器注册：通过@app.exception_handler装饰器绑定特定异常类型到处理函数

2.1.2 关键异常类型区分

异常类型	触发场景	继承关系
ValidationError	手动调用模型验证时抛出	Pydantic原生异常
RequestValidationError	FastAPI自动参数校验失败	继承自ValidationError

2.2 核心处理逻辑剖析

2.2.1 错误数据结构解构

# 原始错误条目结构示例
{
   
    "type": "value_error",       # 错误大类
    "loc": ("body", "age"),      # 错误位置元组
    "msg": "输入值不是合法整数",   # 原始错误描述
    "input": "eighteen"          # 客户端原始输入
}

字段深度说明：

• loc定位器：

  • 遵循(位置类型, 字段路径...)结构
  • 位置类型可能为：body, query, path, header, cookie
  • 嵌套字段示例：("body", "user", "address", "city")

• 常见错误类型：

  # Pydantic预定义错误类型参考
  "missing"            # 必填字段缺失
  "value_error"        # 值校验失败
  "type_error"         # 类型不匹配
  "assertion_error"    # 自定义校验断言失败
  

2.2.2 错误信息处理流程

def