Unified Exception Handling in Spring Boot Using @ControllerAdvice, Assert, and Enum-based Error Codes

In many Java backend projects a large amount of code is filled with try { ... } catch { ... } finally { ... } blocks, which makes the source hard to read and maintain. The article first compares an ugly try‑catch style with a more elegant controller implementation.

Spring 3.2 introduced @ControllerAdvice and @ExceptionHandler, which allow developers to define global exception handling logic that applies to all controllers without duplicating code in each class.

The article presents a custom Assert utility that wraps null‑checks and throws a specific exception when a condition fails. Example implementation:

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

To avoid creating many exception classes, an enum is used to hold error codes and messages. The enum implements a BusinessExceptionAssert interface that creates a BusinessException with the appropriate code and formatted message. Example enum snippet:

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

The unified exception handler class annotated with @ControllerAdvice defines several @ExceptionHandler methods: handling BusinessException, generic BaseException, servlet‑related exceptions, binding and validation errors, and a catch‑all Exception. Each method logs the error and returns a consistent ErrorResponse containing code and message. Example handler method:

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

For 404 handling, the default behavior is changed by setting spring.mvc.throw-exception-if-no-handler-found=true and disabling static resource mappings, so that a NoHandlerFoundException is thrown and can be processed by the unified handler.

In service code the enum‑based assert is used to validate inputs, e.g. ResponseEnum.LICENCE_NOT_FOUND.assertNotNull(licence);, which throws the corresponding exception without manual if checks.

Overall, the approach eliminates most repetitive try‑catch code, provides a single place for error response formatting, supports internationalized messages, and makes the backend codebase cleaner and more maintainable.