SpringBoot全局异常处理与参数校验功能实现

后端接口报错，要是直接让异常往外抛，前端收到的要么是一大段 Tomcat 默认的 HTML 错误页，要么是乱七八糟的堆栈信息。前端同学一看就懵了——这到底是啥错？该提示用户什么？

所以得有一层兜底：不管哪层出了什么岔子，返回给前端的东西始终是统一格式的 JSON——有错误码、有错误信息，前端拿到手就能稳稳地做判断和处理。

参数校验也得一起安排上。Controller 里别写一堆 if (xxx == null)，用注解声明规则，校验不通过直接抛异常，再由全局处理器统一拦截、统一返回。代码干净，逻辑也清晰。

引入依赖

@ControllerAdvice 和 @ExceptionHandler 这些都在 spring-boot-starter-web 里，如果你项目已经用了 Web 模块，这部分就不用重复加了。

但参数校验的依赖需要单独拎出来：

    org.springframework.boot
    spring-boot-starter-validation

注意一下版本差异：Spring Boot 2.x 时代，validation 是内嵌在 spring-boot-starter-web 里的，到了 3.x 就被拆出来了。如果不加这个依赖，@NotBlank、@Valid 这些注解不会报编译错误，但运行时校验根本不生效——加了个寂寞，所有参数直接放行。

第一步：搭异常体系

common

先搭两个基础的东西：异常接口 + 异常类。这两个放在 common 模块，全项目都能复用。

BaseExceptionInterface

public interface BaseExceptionInterface {
    String getErrorCode();
    String getErrorMessage();
}

一个很简单的接口，它就规定一件事：异常必须包含错误码和错误信息。后面我们的枚举实现它，BizException 也依赖它，所有东西都围绕这个约定来走。

BizException

BizException 代表业务异常，每个模块都可能出现，所以定义在 common 里最合适。

@Getter
@Setter
public class BizException extends RuntimeException {
    private String errorCode;
    private String errorMessage;
    public BizException(BaseExceptionInterface baseExceptionInterface) {
        this.errorCode = baseExceptionInterface.getErrorCode();
        this.errorMessage = baseExceptionInterface.getErrorMessage();
    }
}

继承 RuntimeException，有两个好处：抛的时候不用在方法签名上加 throws，Spring 对运行时异常默认也会做事务回滚。构造参数只接收 BaseExceptionInterface，不让你随便写 new BizException("随便写的错")——所有异常必须提前在枚举里定义好，方便统一管理。

具体业务模块

接下来定义你这个模块可能有哪些异常。

ResponseCodeEnum

@Getter
@AllArgsConstructor
public enum ResponseCodeEnum implements BaseExceptionInterface {
    // 通用异常
    SYSTEM_ERROR("AUTH-10000", "出错啦，后台小哥正在努力修复中..."),
    PARAM_NOT_VALID("AUTH-10001", "参数错误"),
    // 业务异常往后加
    ;
    private final String errorCode;
    private final String errorMessage;
}

这里有个小巧妙：BaseExceptionInterface 定义的 getErrorCode 和 getErrorMessage 两个方法，枚举里定义了两个变量，加上 @Getter，刚好就把接口方法给实现了。巧不巧？

抛一个业务异常就一句话：

throw new BizException(ResponseCodeEnum.SYSTEM_ERROR);

三者关系

BizException 的构造参数是 BaseExceptionInterface（接口），不是 ResponseCodeEnum（具体枚举）。所以层级关系是这样的：

BizException 构造参数
        ↓ 依赖
BaseExceptionInterface（接口：规定必须有 errorCode + errorMessage）
        ↑ 实现
ResponseCodeEnum（枚举：集中管理所有错误码）

• 接口 起约定作用：不管哪个模块、哪个枚举，只要你实现了这两个 getter，就能丢进 BizException
• 枚举 起集中管理作用：所有错误码一处定义，不散落
• BizException 只认接口不认枚举，auth 模块的 AuthResponseCodeEnum、order 模块的 OrderResponseCodeEnum，只要实现了接口，都能用

如果直接用 new BizException(String, String)，错误码就会散落在项目各个角落，改一个提示语得全项目搜索，想看看系统里有哪些错误码更是无从下手。

第二步：全局异常处理器

@ControllerAdvice
@Slf4j
public class GlobalExceptionHandler {
    /** 业务异常 */
    @ExceptionHandler({ BizException.class })
    @ResponseBody
    public Response