php 技术随笔

Spring Boot 统一异常处理：@RestControllerAdvice 实战

H文和发布于年 ·

字号

在 Spring Boot 项目中，如果每个接口都手写 try-catch，代码会变得又臭又长。通过 @RestControllerAdvice + @ExceptionHandler，可以全局拦截异常并统一返回格式，既优雅又便于前端处理。

一、定义统一返回结构

public class Result<T> {
    private int code;
    private String msg;
    private T data;
    // 省略 getter/setter 与静态工厂方法
}

二、编写全局异常处理器

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BusinessException.class)
    public Result<Void> handleBiz(BusinessException e) {
        return Result.fail(e.getCode(), e.getMessage());
    }

    @ExceptionHandler(Exception.class)
    public Result<Void> handleUnknown(Exception e) {
        return Result.fail(500, "系统异常，请稍后重试");
    }
}

三、常见异常分类处理

参数校验失败：MethodArgumentNotValidException → 返回 400 及字段错误信息。
资源不存在：自定义 BusinessException → 返回业务码。
无权限：AccessDeniedException → 返回 403。
兜底：Exception → 返回 500，避免把堆栈直接暴露给前端。

四、注意事项

异常处理器方法上的 @ExceptionHandler 按最具体异常优先匹配。
不要把原始异常信息（含 SQL、路径）直接返回给前端，存在安全风险。
配合 @ResponseStatus 可同时设置 HTTP 状态码。