Unified Exception Handling in Spring: Using @ControllerAdvice, Assertions, and Enums for Clean Error Management

During development, handling exceptions with repetitive try {...} catch {...} finally {...} blocks leads to noisy and hard‑to‑read code; the article proposes a cleaner approach using Spring's unified exception handling.

Unified Exception Handling is introduced via the @ControllerAdvice annotation, which allows a single class to intercept exceptions thrown from any @Controller or service layer.

The UnifiedExceptionHandler defines several @ExceptionHandler methods, for example:

@ExceptionHandler(value = BusinessException.class)
@ResponseBody
public ErrorResponse handleBusinessException(BaseException e) {
    log.error(e.getMessage(), e);
    return new ErrorResponse(e.getResponseEnum().getCode(), getMessage(e));
}

Custom exceptions extend BaseException, which carries an IResponseEnum containing an error code and message. By implementing BusinessExceptionAssert (which extends Assert), each enum constant can create the appropriate exception without writing separate classes.

public enum ResponseEnum implements BusinessExceptionAssert {
    BAD_LICENCE_TYPE(7001, "Bad licence type."),
    LICENCE_NOT_FOUND(7002, "Licence not found.");
    private final int code;
    private final String message;
    // getters omitted
}

The Assert utility simplifies null checks:

public abstract class Assert {
    public static void notNull(Object obj, String message) {
        if (obj == null) {
            throw new IllegalArgumentException(message);
        }
    }
}

Various servlet‑related exceptions (e.g., NoHandlerFoundException, HttpRequestMethodNotSupportedException, MissingServletRequestParameterException) are captured in handleServletException, mapping each to a specific error code defined in enums such as CommonResponseEnum or ServletResponseEnum.

Environment awareness is added: when the active profile is prod, detailed internal messages are hidden and a generic SERVER_ERROR response is returned.

Finally, the article shows how to standardize API responses with BaseResponse, CommonResponse, ErrorResponse, and shortcut classes R and QR, ensuring every API returns a consistent code, message, and optional data payload.