Unified Exception Handling and Assertion Practices in Spring Boot Backend Development

In modern Java backend development, handling exceptions efficiently is crucial for code readability and maintainability. The article introduces the problems caused by excessive try { ... } catch { ... } finally { ... } blocks and compares a cluttered style with a cleaner, more elegant approach.

Background

Spring 3.2 added the @ControllerAdvice annotation, which can be combined with @ExceptionHandler to define global exception handling logic that applies to all controllers, eliminating the need to repeat exception handling code in each controller class.

What Is Unified Exception Handling?

Unified exception handling centralizes the processing of various exception types—both framework-level (e.g., NoHandlerFoundException , HttpRequestMethodNotSupportedException ) and business-level (custom BusinessException subclasses). By defining a single UnifiedExceptionHandler class annotated with @ControllerAdvice , developers can map specific exceptions to consistent error responses.

Goal

The goal is to eliminate more than 95% of repetitive try-catch blocks by using assertions ( Assert.notNull() , custom Assert utilities) to validate business conditions, allowing developers to focus on core logic while the framework handles error translation.

Implementation Details

1. @ControllerAdvice class defines handlers for:

Business exceptions ( @ExceptionHandler(BusinessException.class) )

Base exceptions ( @ExceptionHandler(BaseException.class) )

Servlet-related exceptions (404, method not allowed, media type mismatches, etc.)

Binding and validation exceptions ( BindException , MethodArgumentNotValidException )

All other unknown exceptions ( @ExceptionHandler(Exception.class) )

2. Each handler logs the error and returns an ErrorResponse containing a code and a localized message . In production environments, generic messages are returned to avoid exposing internal details.

3. Assertion utilities are defined as interfaces with default methods, allowing developers to write concise checks such as:

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

These assertions delegate exception creation to enum instances that implement BusinessExceptionAssert , automatically providing error codes and formatted messages.

4. Example enum definition:

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;
    // getters omitted
}

5. Service layer code uses the assertions to validate inputs before proceeding, e.g.:

private void checkNotNull(Licence licence) {
    ResponseEnum.LICENCE_NOT_FOUND.assertNotNull(licence);
}

6. The article also shows how to configure Spring to throw exceptions for unmapped URLs ( spring.mvc.throw-exception-if-no-handler-found=true ) so that 404 errors are processed by the unified handler.

Response Structure

All API responses share a common structure with fields code , message , and optionally data . Helper classes BaseResponse , CommonResponse , ErrorResponse , and pagination wrapper QueryDataResponse are introduced to standardize success and error payloads.

Testing and Validation

The article provides screenshots of API calls demonstrating how different error scenarios (missing licence, invalid licence type, unsupported HTTP method, validation failures, database errors) are captured and returned with appropriate codes and messages.

Conclusion

By combining @ControllerAdvice , assertion utilities, and enum‑based error definitions, developers can achieve clean, maintainable backend code that handles both business and framework exceptions uniformly, reduces boilerplate, and supports internationalized error messages.