Mastering Unified Exception Handling in Spring Boot: Clean Code, Better Errors

What is Unified Exception Handling

In Java projects a large amount of code is spent on repetitive try { … } catch { … } finally { … } blocks, which reduces readability. By moving exception handling out of individual controllers and services we can simplify business logic.

Goal

Eliminate more than 95% of explicit try‑catch statements and replace them with Assert checks that only validate business conditions, while a central handler returns a uniform {code, message, data} JSON response.

Unified Exception Handler

The class annotated with @ControllerAdvice defines several @ExceptionHandler methods. It distinguishes servlet‑level exceptions (404, method not supported, missing parameters, etc.), custom business exceptions, and unknown exceptions, and maps them to an ErrorResponse object.

@Slf4j
@Component
@ControllerAdvice
public class UnifiedExceptionHandler {
    // ... handler methods ...
}

Custom Assertions with Enums

Define an IResponseEnum that holds an error code and message. An interface BusinessExceptionAssert extends both the enum and Spring’s Assert. Each enum constant (e.g., BAD_LICENCE_TYPE, LICENCE_NOT_FOUND) creates a specific BusinessException when the assertion fails.

public enum ResponseEnum implements BusinessExceptionAssert {
    BAD_LICENCE_TYPE(7001, "Bad licence type."),
    LICENCE_NOT_FOUND(7002, "Licence not found.");
    // getters …
}

Exception Classification

Controller‑pre exceptions: NoHandlerFoundException, HttpRequestMethodNotSupportedException, etc.

Custom business exceptions: BusinessException, BaseException.

Unknown exceptions: any other Exception.

Unified Response Structure

All API responses inherit from BaseResponse. Successful results use CommonResponse (or shortcut R<T></code) with a <code>data field; paginated results use QueryDataResponse (or QR<T></code) containing <code>totalCount, pageNo, pageSize, and records.

Testing Results

Various scenarios (missing licence, invalid licence type, 404, unsupported HTTP method, validation errors, database errors) are captured by the unified handler and return a JSON object with the appropriate code and message. Screenshots illustrate the responses.

Conclusion

By combining assertions, enum‑based error codes, and a global @ControllerAdvice handler, most exceptions become easy to manage, internationalizable, and consistent across the backend service. The approach also reduces boilerplate and improves code readability.