Mastering Unified Exception Handling in Spring Boot: Clean Code & Best Practices

What Is Unified Exception Handling

Spring 3.2 introduced @ControllerAdvice which can be combined with @ExceptionHandler, @InitBinder, and @ModelAttribute to apply exception handling across all controllers.

Why Not Use Try‑Catch Everywhere

Scattered try { ... } catch { ... } finally { ... } blocks lead to redundant code and poor readability. A unified approach keeps business logic clean.

Using Assert for Validation

Replace manual null checks with Assert.notNull(object, "Message"). Example test methods show the difference between using Assert and traditional

if (obj == null) { throw new IllegalArgumentException(...); }

.

Enum‑Based Error Codes

Define an IResponseEnum with code and message. Implement BusinessExceptionAssert to create exceptions based on enum values, eliminating the need for many custom exception classes.

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;
}

Unified Exception Handler Class

@Slf4j
@Component
@ControllerAdvice
public class UnifiedExceptionHandler {
    @ExceptionHandler(BusinessException.class)
    @ResponseBody
    public ErrorResponse handleBusinessException(BaseException e) {
        log.error(e.getMessage(), e);
        return new ErrorResponse(e.getResponseEnum().getCode(), getMessage(e));
    }
    // ... other handlers for servlet exceptions, bind exceptions, validation, unknown exceptions
}

The handler categorizes exceptions into:

Pre‑controller exceptions (404, method not supported, etc.)

Business exceptions (custom BusinessException)

Unknown exceptions (fallback)

Standardized API Response

All responses share code and message. Successful results use CommonResponse or QueryDataResponse. For brevity, wrapper classes R<T> and QR<T> are introduced.

Testing the Unified Handler

Examples demonstrate handling of missing resources, invalid licence types, unsupported HTTP methods, parameter binding errors, and database errors. Screenshots (omitted here) show consistent JSON responses with appropriate error codes and messages.

Internationalization

Error messages are fetched via UnifiedMessageSource using keys like response.LICENCE_NOT_FOUND, allowing locale‑specific messages.

Production‑Environment Considerations

In production, detailed exception details are hidden; generic messages such as "Network error" are returned to avoid exposing internal stack traces.

Conclusion

By combining Assert, enum‑based error definitions, and a global @ControllerAdvice handler, most exceptions can be captured and returned in a uniform {code, message, data} format, improving code readability and maintainability for Java backend projects.