Unified Exception Handling in Spring Boot Using @ControllerAdvice, Assert, and Enum‑Based Error Codes

In large Java Spring projects, developers often spend half of their time writing repetitive try { … } catch { … } blocks, which makes the code noisy and hard to read. The article proposes a clean alternative by using Spring's @ControllerAdvice together with a custom Assert utility and an enum that defines error codes and messages.

The Assert interface provides default methods such as assertNotNull(Object obj) that internally throw a business exception defined by an enum instance. Example:

public interface Assert {
    default void assertNotNull(Object obj) {
        if (obj == null) {
            throw newException();
        }
    }
    BaseException newException(Object... args);
}

An enum implementing BusinessExceptionAssert maps each error scenario to a specific code and message, e.g., BAD_LICENCE_TYPE(7001, "Bad licence type.") . Controllers can then validate inputs with a single line:

ResponseEnum.BAD_LICENCE_TYPE.assertNotNull(licenceTypeEnum);
ResponseEnum.LICENCE_NOT_FOUND.assertNotNull(licence);

The unified exception handler, annotated with @ControllerAdvice , catches all exceptions, distinguishes between business, servlet, and unknown errors, and returns a standardized JSON response containing code and message . It also supports internationalization by looking up messages from a message source.

Configuration snippets show how to force Spring to throw a NoHandlerFoundException for 404 errors, enabling them to be handled uniformly. The article demonstrates the approach with a sample LicenceService that uses MyBatis‑Plus for data access, and provides screenshots of the resulting API responses for various error scenarios.

Overall, the pattern eliminates the need for numerous custom exception classes, improves readability, and ensures consistent error handling across the entire backend service.