Master Global Exception Handling in Spring Boot: A Complete Guide

Preface

During Spring Boot development, handling numerous try…catch…finally blocks across MVC layers leads to redundant code and reduced readability. Defining a global unified exception handler allows business layers to avoid repetitive error handling.

Benefits

Copy the code into the project and enable it with simple configuration.

Flexibly extend to finer‑grained business‑specific exceptions.

1. Unified Response Class (AjaxResult)

public class AjaxResult {
    // Whether the request succeeded
    private Boolean success;
    // Status code
    private Integer code;
    // Message
    private String msg;
    // Data payload
    private Object data;

    public AjaxResult() {}

    // Custom constructor
    public AjaxResult(Boolean success, Integer code, String msg, Object data) {
        this.success = success;
        this.code = code;
        this.msg = msg;
        this.data = data;
    }

    // Factory method for business exceptions
    public static AjaxResult defineError(BusinessException de) {
        AjaxResult result = new AjaxResult();
        result.setSuccess(false);
        result.setCode(de.getErrorCode());
        result.setMsg(de.getErrorMsg());
        result.setData(null);
        return result;
    }

    // Factory method for other errors
    public static AjaxResult otherError(ErrorEnum errorEnum) {
        AjaxResult result = new AjaxResult();
        result.setMsg(errorEnum.getErrorMsg());
        result.setCode(errorEnum.getErrorCode());
        result.setSuccess(false);
        result.setData(null);
        return result;
    }

    // Getters and setters omitted for brevity
}

2. Custom Exception Class (BusinessException)

public class BusinessException extends RuntimeException {
    protected Integer errorCode;
    protected String errorMsg;

    public BusinessException() {}

    public BusinessException(Integer errorCode, String errorMsg) {
        this.errorCode = errorCode;
        this.errorMsg = errorMsg;
    }

    public Integer getErrorCode() { return errorCode; }
    public void setErrorCode(Integer errorCode) { this.errorCode = errorCode; }
    public String getErrorMsg() { return errorMsg; }
    public void setErrorMsg(String errorMsg) { this.errorMsg = errorMsg; }
}

3. Error Enum (ErrorEnum)

public enum ErrorEnum {
    SUCCESS(200, "成功"),
    NO_PERMISSION(403, "你没得权限"),
    NO_AUTH(401, "未登录"),
    NOT_FOUND(404, "未找到该资源!"),
    INTERNAL_SERVER_ERROR(500, "服务器异常请联系管理员");

    private Integer errorCode;
    private String errorMsg;

    ErrorEnum(Integer errorCode, String errorMsg) {
        this.errorCode = errorCode;
        this.errorMsg = errorMsg;
    }

    public Integer getErrorCode() { return errorCode; }
    public String getErrorMsg() { return errorMsg; }
}

4. Global Exception Handler (GlobalExceptionHandler)

@RestControllerAdvice
public class GlobalExceptionHandler {
    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    // Handle custom business exceptions
    @ExceptionHandler(BusinessException.class)
    public AjaxResult bizExceptionHandler(BusinessException e) {
        log.error(e.getMessage(), e);
        return AjaxResult.defineError(e);
    }

    // Handle all other exceptions
    @ExceptionHandler(Exception.class)
    public AjaxResult exceptionHandler(Exception e) {
        log.error(e.getMessage(), e);
        return AjaxResult.otherError(ErrorEnum.INTERNAL_SERVER_ERROR);
    }
}

5. Test Result

The test demonstrates that the unified response format is returned correctly for both successful and error scenarios.