实时AI助手｜2026-04-09：@RestControllerAdvice全局异常处理原理与实战

@RestController

public class UserController {
    
    @GetMapping("/user/{id}")
    public ResultVO getUser(@PathVariable Long id) {
        try {
            User user = userService.getById(id);
            if (user == null) {
                throw new RuntimeException("用户不存在");
            }
            return ResultVO.success(user);
        } catch (Exception e) {
            return ResultVO.fail(500, "查询用户失败：" + e.getMessage());
        }
    }
    
    @PostMapping("/user")
    public ResultVO createUser(@RequestBody UserVO vo) {
        try {
            userService.create(vo);
            return ResultVO.success();
        } catch (Exception e) {
            return ResultVO.fail(500, "创建用户失败：" + e.getMessage());
        }
    }
    // ... 每个接口都要写重复的 try-catch
}

@RestControllerAdvice = @ControllerAdvice + @ResponseBody

@ControllerAdvice
public class GlobalViewExceptionHandler {
    @ExceptionHandler(Exception.class)
    public String handleException(Exception ex, Model model) {
        model.addAttribute("error", ex.getMessage());
        return "error";  // 返回视图名称，跳转到error页面
    }
}

@RestControllerAdvice
public class GlobalApiExceptionHandler {
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorDetails> handleException(Exception ex) {
        return ResponseEntity.status(500).body(new ErrorDetails(ex.getMessage()));
    }
}

// 统一响应类（成功响应）
public class ApiResponse<T> {
    private long timestamp;
    private String message;
    private T data;
    
    public ApiResponse(long timestamp, String message, T data) {
        this.timestamp = timestamp;
        this.message = message;
        this.data = data;
    }
    // getter/setter...
}

// 错误响应类（错误响应）
public class ErrorResponse {
    private int status;
    private String message;
    private long timestamp;
    
    public ErrorResponse(int status, String message, long timestamp) {
        this.status = status;
        this.message = message;
        this.timestamp = timestamp;
    }
    // getter/setter...
}

// 自定义业务异常（继承RuntimeException，Spring会自动传播）
public class BusinessException extends RuntimeException {
    private int code;
    
    public BusinessException(int code, String message) {
        super(message);
        this.code = code;
    }
    
    public int getCode() { return code; }
}

@Slf4j
@RestControllerAdvice  // ⭐ 核心注解：声明全局异常处理类
public class GlobalExceptionHandler {
    
    // 处理自定义业务异常
    @ExceptionHandler(BusinessException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)  // 设置HTTP状态码为400
    public ErrorResponse handleBusinessException(BusinessException e) {
        log.warn("业务异常: code={}, message={}", e.getCode(), e.getMessage());
        return new ErrorResponse(e.getCode(), e.getMessage(), System.currentTimeMillis());
    }
    
    // 处理参数校验异常
    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ErrorResponse handleValidationException(MethodArgumentNotValidException e) {
        String errorMsg = e.getBindingResult().getFieldErrors().stream()
            .map(fieldError -> fieldError.getField() + ":" + fieldError.getDefaultMessage())
            .collect(Collectors.joining(", "));
        return new ErrorResponse(400, errorMsg, System.currentTimeMillis());
    }
    
    // 统一兜底：处理所有未匹配到的异常
    @ExceptionHandler(Exception.class)
    @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
    public ErrorResponse handleGlobalException(Exception e) {
        log.error("系统异常: {}", e.getMessage(), e);
        return new ErrorResponse(500, "服务器内部错误：" + e.getMessage(), System.currentTimeMillis());
    }
}

@RestController
public class UserController {
    
    @GetMapping("/user/{id}")
    public ApiResponse<User> getUser(@PathVariable Long id) {
        if (id == null || id <= 0) {
            throw new BusinessException(400, "用户ID不合法");
        }
        User user = userService.getById(id);
        if (user == null) {
            throw new BusinessException(404, "用户不存在");
        }
        return new ApiResponse<>(System.currentTimeMillis(), "success", user);
    }
    // 无需任何try-catch！
}

protected void doDispatch(HttpServletRequest request, 
                          HttpServletResponse response) throws Exception {
    Exception dispatchException = null;
    try {
        // 找到Handler（Controller方法）
        HandlerExecutionChain mappedHandler = getHandler(processedRequest);
        // 执行Controller方法
        mv = ha.handle(processedRequest, response, mappedHandler.getHandler());
    } catch (Exception ex) {
        // ⭐ 统一捕获！所有Controller方法抛出的异常都会落到这里
        dispatchException = ex;
    }
    // 统一处理结果（正常or异常）
    processDispatchResult(request, response, mappedHandler, mv, dispatchException);
}