Spring Boot 统一异常处理：实现、原理与最佳实践

为了规范响应格式，建议封装通用的 Result 对象：

import lombok.Data;
import com.example.enums.ResultStatus;

@Data
public class Result<T> {
    private ResultStatus code;
    private String errMsg;
    private T data;

    public static <T> Result success(T data) {
        Result result = new Result<>();
        result.setCode(ResultStatus.SUCCESS);
        result.setData(data);
        return result;
    }

    public static Result fail(String msg) {
        Result result = new Result<>();
        result.setCode(ResultStatus.FAIL);
        result.setErrMsg(msg);
        return result;
    }

    public static Result fail(ResultStatus status, String msg) {
        Result result = new Result<>();
        result.setCode(status);
        result.setErrMsg(msg);
        return result;
    }
}

异常匹配优先级源码解析

在实际开发中，我们常遇到一个问题：当同时存在处理父类异常（如 Exception）和子类异常（如 ArithmeticException）的方法时，系统究竟会调用哪一个？

以访问 /test/t1 触发除零异常为例，我们可以通过调试模式深入 ExceptionHandlerMethodResolver 类的 getMapperMethod 方法来观察流程。

系统首先会收集当前上下文中所有能处理该异常类型的候选方法。对于 ArithmeticException，由于它既是 RuntimeException 的子类，也是 Exception 的子类，因此 handlerException(Exception) 和 handlerException(ArithmeticException) 都会被初步匹配到。

关键在于后续的排序逻辑。框架会根据异常的层级深度进行排序，优先选择最具体的异常类型。也就是说，子类异常的处理方法优先级高于父类异常。经过排序后，matches 集合中顺序发生变化，最终返回深度最浅（即最具体）的异常处理器。

这就解释了为什么针对 ArithmeticException 会调用专门的方法，而不是通用的 Exception 处理方法。同理，NullPointerException 也会优先于 Exception 被捕获。

业务价值

采用统一异常处理方案主要有以下几方面优势：

提升用户体验与安全性 通过统一封装，可以为前端提供一致且友好的错误提示，避免直接暴露后端堆栈跟踪或技术细节，防止敏感信息泄露。

解耦业务逻辑 将异常处理从业务代码中剥离，使 Controller 更专注于业务流转。当处理策略变更时，只需修改全局配置，降低了维护成本。

便于监控与日志 集中处理使得异常统计和日志记录更加容易，有助于快速定位故障根源并进行性能优化。同时，统一的代码风格也提升了项目的可读性。

测试验证

以下是一个简单的测试控制器，用于触发不同类型的异常：

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RequestMapping("/test")
@RestController
public class TestController {

    @RequestMapping("/t1")
    public String t1() {
        int result = 10 / 0;
        return "string";
    }

    @RequestMapping("/t2")
    public Integer t2() {
        String str = null;
        System.out.println(str.length());
        return 1;
    }

    @RequestMapping("/t3")
    public Boolean t3() {
        Integer[] integers = new Integer[]{1, 2, 3, 4};
        System.out.println(integers[5]);
        return true;
    }
}

运行上述接口，控制台日志会记录对应的异常信息，而前端接收到的则是经过 Result 封装的标准响应。这种机制确保了无论底层抛出何种异常，上层交互始终稳定可控。