[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6},"actionData","errors","routes/blog-tag",{"_7":8,"_9":10},"tag",{"_31":82,"_72":83,"_35":84},"articles",{"_11":12,"_13":14,"_15":16,"_17":16,"_18":19,"_20":21,"_22":23,"_24":23,"_25":16,"_26":27},"content",[30],"pageable",{"_28":21,"_29":19},"totalElements",1,"totalPages","size",10,"number",0,"first",true,"last","numberOfElements","empty",false,"page_number","page_size",{"_31":32,"_33":34,"_35":36,"_37":38,"_11":39,"_40":-5,"_41":23,"_42":27,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":52,"_54":55,"_56":57,"_58":59,"_60":52,"_61":16,"_62":63,"_64":65,"_66":67,"_68":69,"_70":71},"id",15,"title","Exception Hierarchy Design","slug","clean-code-part-14-exception-hierarchy","excerpt","Design exception hierarchies that communicate intent, enable proper handling, and integrate cleanly with Spring Boot using @ControllerAdvice.","# Advanced Clean Code Patterns Part 14: Exception Hierarchy Design\n\nWell-designed exceptions are crucial for maintainable error handling. This article covers how to design exception hierarchies that communicate intent, enable proper handling, and integrate cleanly with Spring Boot.\n\n## 📋 At a Glance\n\n| Aspect | Details |\n|--------|---------|\n| Types | Checked vs Unchecked, Business vs Technical |\n| Best Practices | Specific types, meaningful messages, proper context |\n| Spring Integration | @ControllerAdvice, ResponseStatusException |\n| Anti-patterns | Generic exceptions, empty catch, exception swallowing |\n\n---\n\n## 🎯 What You'll Learn\n\n- **Exception hierarchy design** principles\n- **Business vs technical** exceptions\n- **Exception context** and meaningful messages\n- **Spring Boot integration** with @ControllerAdvice\n- **Anti-patterns** to avoid\n\n---\n\n## Production Story: The Generic Exception Disaster\n\nA payment system used generic exceptions everywhere:\n\n```java\n// ❌ Generic exceptions - impossible to handle correctly\npublic void processPayment(Payment payment) throws Exception {\n try {\n gateway.charge(payment);\n } catch (Exception e) {\n throw new Exception(\"Payment failed\"); // Lost all context!\n }\n}\n\n// Caller has no idea what went wrong\ntry {\n paymentService.processPayment(payment);\n} catch (Exception e) {\n // Is it network error? Invalid card? Fraud? Insufficient funds?\n // We have no idea! Show generic error to user.\n showError(\"Something went wrong\");\n}\n```\n\n**Problems:**\n- No way to distinguish recoverable vs fatal errors\n- Lost original cause and context\n- Generic error messages to users\n- No specific logging or metrics\n- Impossible to retry appropriately\n\n**The fix:** Well-designed exception hierarchy:\n\n```java\n// ✅ Specific exceptions enable proper handling\npublic void processPayment(Payment payment) {\n try {\n gateway.charge(payment);\n } catch (NetworkException e) {\n throw new PaymentGatewayException(\"Gateway unreachable\", e);\n } catch (CardDeclinedException e) {\n throw new PaymentDeclinedException(e.getReason(), payment.getId());\n } catch (FraudDetectedException e) {\n throw new FraudException(payment.getId(), e.getRiskScore());\n }\n}\n\n// Caller can handle appropriately\ntry {\n paymentService.processPayment(payment);\n} catch (PaymentDeclinedException e) {\n showError(\"Card declined: \" + e.getReason());\n suggestAlternativePayment();\n} catch (PaymentGatewayException e) {\n scheduleRetry(payment);\n showError(\"Temporary issue, retrying...\");\n} catch (FraudException e) {\n blockUser();\n alertSecurityTeam(e);\n}\n```\n\n---\n\n## Mental Model: Exception Hierarchy\n\n```text\n┌─────────────────────────────────────────────────────────────────┐\n│ EXCEPTION HIERARCHY DESIGN │\n├─────────────────────────────────────────────────────────────────┤\n│ │\n│ RuntimeException │\n│ │ │\n│ ┌───────────────┼───────────────┐ │\n│ │ │ │ │\n│ ▼ ▼ ▼ │\n│ ApplicationException TechnicalException ValidationException │\n│ │ │ │\n│ ┌─────┼─────┐ ┌───┼───┐ │\n│ │ │ │ │ │ │\n│ ▼ ▼ ▼ ▼ ▼ │\n│ Order Payment User Database Network │\n│ Exception Exception Exception │\n│ │\n│ ───────────────────────────────────────────────────────────── │\n│ │\n│ BUSINESS EXCEPTIONS (4xx) TECHNICAL EXCEPTIONS (5xx) │\n│ ┌────────────────────────┐ ┌────────────────────────┐ │\n│ │ - User can fix │ │ - System issue │ │\n│ │ - Shown to user │ │ - Generic message │ │\n│ │ - Don't retry │ │ - May retry │ │\n│ │ - Log at WARN │ │ - Log at ERROR │ │\n│ └────────────────────────┘ └────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## 🔬 Deep Dive\n\n### Pattern 1: Base Exception Design\n\n```java\n// ✅ Well-designed base exception\n\npublic abstract class ApplicationException extends RuntimeException {\n\n private final String errorCode;\n private final Map context;\n private final Instant timestamp;\n\n protected ApplicationException(String message, String errorCode) {\n this(message, errorCode, null, Map.of());\n }\n\n protected ApplicationException(String message, String errorCode,\n Throwable cause, Map context) {\n super(message, cause);\n this.errorCode = errorCode;\n this.context = new HashMap<>(context);\n this.timestamp = Instant.now();\n }\n\n public String getErrorCode() {\n return errorCode;\n }\n\n public Map getContext() {\n return Collections.unmodifiableMap(context);\n }\n\n public Instant getTimestamp() {\n return timestamp;\n }\n\n // For logging\n @Override\n public String toString() {\n return String.format(\"[%s] %s: %s (context: %s)\",\n errorCode, getClass().getSimpleName(), getMessage(), context);\n }\n}\n\n// Business exceptions - user can potentially fix\npublic abstract class BusinessException extends ApplicationException {\n\n protected BusinessException(String message, String errorCode) {\n super(message, errorCode);\n }\n\n protected BusinessException(String message, String errorCode,\n Map context) {\n super(message, errorCode, null, context);\n }\n\n public abstract HttpStatus getHttpStatus();\n}\n\n// Technical exceptions - system issues\npublic abstract class TechnicalException extends ApplicationException {\n\n protected TechnicalException(String message, String errorCode, Throwable cause) {\n super(message, errorCode, cause, Map.of());\n }\n\n protected TechnicalException(String message, String errorCode,\n Throwable cause, Map context) {\n super(message, errorCode, cause, context);\n }\n}\n```\n\n---\n\n### Pattern 2: Domain-Specific Exceptions\n\n```java\n// ✅ Order domain exceptions\n\npublic class OrderException extends BusinessException {\n private final Long orderId;\n\n public OrderException(String message, String errorCode, Long orderId) {\n super(message, errorCode, Map.of(\"orderId\", orderId));\n this.orderId = orderId;\n }\n\n public Long getOrderId() {\n return orderId;\n }\n\n @Override\n public HttpStatus getHttpStatus() {\n return HttpStatus.BAD_REQUEST;\n }\n}\n\npublic class OrderNotFoundException extends OrderException {\n public OrderNotFoundException(Long orderId) {\n super(\"Order not found: \" + orderId, \"ORDER_NOT_FOUND\", orderId);\n }\n\n @Override\n public HttpStatus getHttpStatus() {\n return HttpStatus.NOT_FOUND;\n }\n}\n\npublic class OrderAlreadyExistsException extends OrderException {\n public OrderAlreadyExistsException(Long orderId) {\n super(\"Order already exists: \" + orderId, \"ORDER_ALREADY_EXISTS\", orderId);\n }\n\n @Override\n public HttpStatus getHttpStatus() {\n return HttpStatus.CONFLICT;\n }\n}\n\npublic class OrderNotModifiableException extends OrderException {\n private final OrderStatus currentStatus;\n\n public OrderNotModifiableException(Long orderId, OrderStatus status) {\n super(String.format(\"Order %d cannot be modified in status %s\", orderId, status),\n \"ORDER_NOT_MODIFIABLE\", orderId);\n this.currentStatus = status;\n }\n\n public OrderStatus getCurrentStatus() {\n return currentStatus;\n }\n}\n\n// ✅ Payment domain exceptions\npublic class PaymentException extends BusinessException {\n private final String transactionId;\n\n public PaymentException(String message, String errorCode, String transactionId) {\n super(message, errorCode, Map.of(\"transactionId\", transactionId));\n this.transactionId = transactionId;\n }\n\n @Override\n public HttpStatus getHttpStatus() {\n return HttpStatus.PAYMENT_REQUIRED;\n }\n}\n\npublic class InsufficientFundsException extends PaymentException {\n private final BigDecimal required;\n private final BigDecimal available;\n\n public InsufficientFundsException(String transactionId,\n BigDecimal required,\n BigDecimal available) {\n super(String.format(\"Insufficient funds: required %s, available %s\",\n required, available), \"INSUFFICIENT_FUNDS\", transactionId);\n this.required = required;\n this.available = available;\n }\n}\n\npublic class PaymentDeclinedException extends PaymentException {\n private final DeclineReason reason;\n\n public PaymentDeclinedException(String transactionId, DeclineReason reason) {\n super(\"Payment declined: \" + reason.getDescription(),\n \"PAYMENT_DECLINED\", transactionId);\n this.reason = reason;\n }\n}\n```\n\n---\n\n### Pattern 3: Validation Exceptions\n\n```java\n// ✅ Validation exception with multiple errors\n\npublic class ValidationException extends BusinessException {\n private final List errors;\n\n public ValidationException(List errors) {\n super(formatMessage(errors), \"VALIDATION_FAILED\",\n Map.of(\"errorCount\", errors.size()));\n this.errors = List.copyOf(errors);\n }\n\n public ValidationException(String field, String message) {\n this(List.of(new ValidationError(field, message)));\n }\n\n public List getErrors() {\n return errors;\n }\n\n @Override\n public HttpStatus getHttpStatus() {\n return HttpStatus.BAD_REQUEST;\n }\n\n private static String formatMessage(List errors) {\n return errors.stream()\n .map(e -> e.field() + \": \" + e.message())\n .collect(Collectors.joining(\", \"));\n }\n}\n\npublic record ValidationError(\n String field,\n String message,\n Object rejectedValue\n) {\n public ValidationError(String field, String message) {\n this(field, message, null);\n }\n}\n\n// Usage\nList errors = new ArrayList<>();\n\nif (email == null || !email.contains(\"@\")) {\n errors.add(new ValidationError(\"email\", \"Invalid email format\", email));\n}\nif (age != null && age < 18) {\n errors.add(new ValidationError(\"age\", \"Must be 18 or older\", age));\n}\n\nif (!errors.isEmpty()) {\n throw new ValidationException(errors);\n}\n```\n\n---\n\n### Pattern 4: Technical Exceptions\n\n```java\n// ✅ Technical exceptions for system issues\n\npublic class DatabaseException extends TechnicalException {\n private final String operation;\n\n public DatabaseException(String message, String operation, Throwable cause) {\n super(message, \"DATABASE_ERROR\", cause,\n Map.of(\"operation\", operation));\n this.operation = operation;\n }\n\n public static DatabaseException connectionFailed(Throwable cause) {\n return new DatabaseException(\"Database connection failed\",\n \"connect\", cause);\n }\n\n public static DatabaseException queryFailed(String query, Throwable cause) {\n return new DatabaseException(\"Query execution failed\",\n \"query\", cause);\n }\n}\n\npublic class ExternalServiceException extends TechnicalException {\n private final String serviceName;\n private final int statusCode;\n\n public ExternalServiceException(String serviceName, int statusCode,\n String message, Throwable cause) {\n super(message, \"EXTERNAL_SERVICE_ERROR\", cause,\n Map.of(\"service\", serviceName, \"statusCode\", statusCode));\n this.serviceName = serviceName;\n this.statusCode = statusCode;\n }\n\n public boolean isRetryable() {\n return statusCode >= 500 || statusCode == 429;\n }\n}\n\npublic class ConfigurationException extends TechnicalException {\n public ConfigurationException(String property, String message) {\n super(String.format(\"Configuration error for '%s': %s\", property, message),\n \"CONFIGURATION_ERROR\", null,\n Map.of(\"property\", property));\n }\n}\n```\n\n---\n\n### Pattern 5: Spring Boot Integration\n\n```java\n// ✅ Global exception handler\n\n@RestControllerAdvice\npublic class GlobalExceptionHandler {\n\n private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);\n\n // Business exceptions - show message to user\n @ExceptionHandler(BusinessException.class)\n public ResponseEntity handleBusinessException(\n BusinessException ex, HttpServletRequest request) {\n\n log.warn(\"Business exception: {}\", ex.toString());\n\n ErrorResponse response = new ErrorResponse(\n ex.getErrorCode(),\n ex.getMessage(),\n ex.getTimestamp(),\n request.getRequestURI(),\n ex.getContext()\n );\n\n return ResponseEntity\n .status(ex.getHttpStatus())\n .body(response);\n }\n\n // Validation exceptions - list all errors\n @ExceptionHandler(ValidationException.class)\n public ResponseEntity handleValidationException(\n ValidationException ex, HttpServletRequest request) {\n\n log.warn(\"Validation failed: {}\", ex.getErrors());\n\n ValidationErrorResponse response = new ValidationErrorResponse(\n ex.getErrorCode(),\n \"Validation failed\",\n ex.getTimestamp(),\n request.getRequestURI(),\n ex.getErrors()\n );\n\n return ResponseEntity\n .badRequest()\n .body(response);\n }\n\n // Technical exceptions - hide details from user\n @ExceptionHandler(TechnicalException.class)\n public ResponseEntity handleTechnicalException(\n TechnicalException ex, HttpServletRequest request) {\n\n log.error(\"Technical exception: {}\", ex.toString(), ex);\n\n ErrorResponse response = new ErrorResponse(\n \"INTERNAL_ERROR\",\n \"An unexpected error occurred\", // Generic message\n ex.getTimestamp(),\n request.getRequestURI(),\n Map.of() // No internal details\n );\n\n return ResponseEntity\n .status(HttpStatus.INTERNAL_SERVER_ERROR)\n .body(response);\n }\n\n // Spring validation\n @ExceptionHandler(MethodArgumentNotValidException.class)\n public ResponseEntity handleSpringValidation(\n MethodArgumentNotValidException ex, HttpServletRequest request) {\n\n List errors = ex.getBindingResult()\n .getFieldErrors()\n .stream()\n .map(fe -> new ValidationError(\n fe.getField(),\n fe.getDefaultMessage(),\n fe.getRejectedValue()))\n .toList();\n\n return handleValidationException(\n new ValidationException(errors), request);\n }\n\n // Fallback for unexpected exceptions\n @ExceptionHandler(Exception.class)\n public ResponseEntity handleUnexpected(\n Exception ex, HttpServletRequest request) {\n\n log.error(\"Unexpected exception\", ex);\n\n ErrorResponse response = new ErrorResponse(\n \"INTERNAL_ERROR\",\n \"An unexpected error occurred\",\n Instant.now(),\n request.getRequestURI(),\n Map.of()\n );\n\n return ResponseEntity\n .status(HttpStatus.INTERNAL_SERVER_ERROR)\n .body(response);\n }\n}\n\n// Error response DTOs\npublic record ErrorResponse(\n String code,\n String message,\n Instant timestamp,\n String path,\n Map details\n) {}\n\npublic record ValidationErrorResponse(\n String code,\n String message,\n Instant timestamp,\n String path,\n List errors\n) {}\n```\n\n---\n\n### Pattern 6: Exception Factory\n\n```java\n// ✅ Exception factory for consistent creation\n\npublic class Exceptions {\n\n private Exceptions() {}\n\n // Not found exceptions\n public static OrderNotFoundException orderNotFound(Long id) {\n return new OrderNotFoundException(id);\n }\n\n public static UserNotFoundException userNotFound(Long id) {\n return new UserNotFoundException(id);\n }\n\n public static EntityNotFoundException notFound(Class type, Object id) {\n return new EntityNotFoundException(type, id);\n }\n\n // Validation\n public static ValidationException validation(String field, String message) {\n return new ValidationException(field, message);\n }\n\n public static ValidationException validation(List errors) {\n return new ValidationException(errors);\n }\n\n // Business rule violations\n public static BusinessRuleException businessRule(String rule, String details) {\n return new BusinessRuleException(rule, details);\n }\n\n // Technical\n public static DatabaseException database(String operation, Throwable cause) {\n return new DatabaseException(\"Database operation failed\", operation, cause);\n }\n}\n\n// Usage - consistent and concise\nthrow Exceptions.orderNotFound(orderId);\nthrow Exceptions.validation(\"email\", \"Invalid format\");\nthrow Exceptions.notFound(Product.class, productId);\n```\n\n---\n\n## ⚠️ Common Mistakes\n\n### Mistake 1: Catching and Swallowing\n\n```java\n// ❌ Swallowing exception - bug hidden forever\ntry {\n processPayment(payment);\n} catch (Exception e) {\n // Silently ignored - no logging, no handling\n}\n\n// ❌ Catch and log only - caller unaware of failure\ntry {\n processPayment(payment);\n} catch (Exception e) {\n log.error(\"Payment failed\", e);\n // But caller thinks it succeeded!\n}\n\n// ✅ Handle or propagate\ntry {\n processPayment(payment);\n} catch (PaymentException e) {\n log.warn(\"Payment failed: {}\", e.getMessage());\n throw e; // Let caller handle\n}\n```\n\n### Mistake 2: Generic Exceptions\n\n```java\n// ❌ Generic exception loses information\nthrow new Exception(\"Something went wrong\");\nthrow new RuntimeException(e);\n\n// ✅ Specific exceptions with context\nthrow new PaymentDeclinedException(transactionId, DeclineReason.INSUFFICIENT_FUNDS);\nthrow new OrderNotFoundException(orderId);\n```\n\n### Mistake 3: Exception for Flow Control\n\n```java\n// ❌ Using exception for normal flow\npublic User findUser(Long id) {\n try {\n return repository.getById(id);\n } catch (NotFoundException e) {\n return createDefaultUser(); // Exception as flow control\n }\n}\n\n// ✅ Use Optional for \"might not exist\"\npublic User findUser(Long id) {\n return repository.findById(id)\n .orElseGet(this::createDefaultUser);\n}\n```\n\n---\n\n## 🐛 Debug This: The Swallowed Exception\n\nA developer reports: \"Orders randomly disappear after checkout! The user sees 'Order placed successfully' but no order is created.\"\n\n```java\n@Service\npublic class CheckoutService {\n\n @Transactional\n public OrderResult checkout(Cart cart) {\n Order order = null;\n try {\n // Create order\n order = orderService.createOrder(cart);\n\n // Process payment\n paymentService.charge(order);\n\n // Reserve inventory\n inventoryService.reserve(order);\n\n // Send confirmation\n emailService.sendConfirmation(order);\n\n } catch (Exception e) {\n log.error(\"Checkout error\", e);\n // BUG: Exception swallowed, but transaction still commits!\n }\n\n return new OrderResult(order.getId(), \"Order placed successfully\");\n }\n}\n\n// Scenario:\n// 1. createOrder() succeeds → order saved\n// 2. charge() succeeds → payment processed\n// 3. reserve() throws InventoryException → logged but swallowed\n// 4. Transaction commits with partial state!\n// 5. User sees \"success\" but inventory not reserved\n```\n\n**Why are orders being created with invalid state?**\n\n---\n\n**✅ Solution:**\n\nThree critical problems:\n\n1. **Exception swallowed** - The catch block logs but doesn't rethrow, so the transaction commits\n2. **No rollback trigger** - `@Transactional` only rolls back on uncaught exceptions (by default RuntimeException)\n3. **Misleading return** - User gets success message even when checkout partially failed\n\n**Correct approach:**\n\n```java\n@Service\npublic class CheckoutService {\n\n @Transactional(rollbackFor = Exception.class) // Rollback on ANY exception\n public OrderResult checkout(Cart cart) {\n try {\n Order order = orderService.createOrder(cart);\n paymentService.charge(order);\n inventoryService.reserve(order);\n emailService.sendConfirmation(order);\n\n return OrderResult.success(order.getId());\n\n } catch (PaymentException e) {\n log.warn(\"Payment failed for cart {}: {}\", cart.getId(), e.getMessage());\n throw new CheckoutException(\"Payment failed: \" + e.getReason(), e);\n\n } catch (InventoryException e) {\n log.warn(\"Inventory unavailable for cart {}: {}\", cart.getId(), e.getMessage());\n throw new CheckoutException(\"Items no longer available\", e);\n\n } catch (Exception e) {\n log.error(\"Unexpected checkout error for cart {}\", cart.getId(), e);\n throw new CheckoutException(\"Checkout failed, please try again\", e);\n }\n }\n}\n\n// Or use specific rollback exceptions\n@Transactional(rollbackFor = {\n CheckoutException.class,\n PaymentException.class,\n InventoryException.class\n})\n```\n\n**The lesson:** Never swallow exceptions in transactional methods. Either rethrow or throw a new exception to trigger rollback. Use `rollbackFor` when dealing with checked exceptions.\n\n---\n\n## 💻 Exercises\n\n### Exercise 1: Design Exception Hierarchy\n⭐ Difficulty: Easy | ⏱️ Time: 15 minutes\n\n**Task:** Design an exception hierarchy for a user management domain.\n\n```java\n// Create exceptions for:\n// - User not found\n// - User already exists (email conflict)\n// - Invalid credentials\n// - Account locked\n// - Password policy violation\n\n// Each should have appropriate error code and HTTP status\n```\n\n**✅ Solution:**\n\n```java\npublic abstract class UserException extends BusinessException {\n private final String userId;\n\n protected UserException(String message, String errorCode, String userId) {\n super(message, errorCode, Map.of(\"userId\", userId != null ? userId : \"unknown\"));\n this.userId = userId;\n }\n\n public String getUserId() {\n return userId;\n }\n}\n\npublic class UserNotFoundException extends UserException {\n public UserNotFoundException(String userId) {\n super(\"User not found: \" + userId, \"USER_NOT_FOUND\", userId);\n }\n\n @Override\n public HttpStatus getHttpStatus() {\n return HttpStatus.NOT_FOUND;\n }\n}\n\npublic class UserAlreadyExistsException extends UserException {\n private final String email;\n\n public UserAlreadyExistsException(String email) {\n super(\"User already exists with email: \" + email, \"USER_ALREADY_EXISTS\", null);\n this.email = email;\n }\n\n @Override\n public HttpStatus getHttpStatus() {\n return HttpStatus.CONFLICT;\n }\n}\n\npublic class InvalidCredentialsException extends UserException {\n public InvalidCredentialsException() {\n super(\"Invalid username or password\", \"INVALID_CREDENTIALS\", null);\n }\n\n @Override\n public HttpStatus getHttpStatus() {\n return HttpStatus.UNAUTHORIZED;\n }\n}\n\npublic class AccountLockedException extends UserException {\n private final Instant lockedUntil;\n\n public AccountLockedException(String userId, Instant lockedUntil) {\n super(\"Account is locked until \" + lockedUntil, \"ACCOUNT_LOCKED\", userId);\n this.lockedUntil = lockedUntil;\n }\n\n @Override\n public HttpStatus getHttpStatus() {\n return HttpStatus.FORBIDDEN;\n }\n}\n\npublic class PasswordPolicyException extends UserException {\n private final List violations;\n\n public PasswordPolicyException(List violations) {\n super(\"Password does not meet requirements: \" + String.join(\", \", violations),\n \"PASSWORD_POLICY_VIOLATION\", null);\n this.violations = List.copyOf(violations);\n }\n\n @Override\n public HttpStatus getHttpStatus() {\n return HttpStatus.BAD_REQUEST;\n }\n}\n```\n\n---\n\n### Exercise 2: Exception Handler\n⭐⭐ Difficulty: Medium | ⏱️ Time: 20 minutes\n\n**Task:** Create a Spring `@ControllerAdvice` that handles exceptions with proper logging and response formatting.\n\n```java\n// Handle:\n// - BusinessException → show message, log WARN\n// - TechnicalException → hide details, log ERROR with stack trace\n// - Spring validation errors → format field errors\n// - Unexpected exceptions → generic message, log ERROR\n```\n\n**✅ Solution:**\n\n```java\n@RestControllerAdvice\n@Slf4j\npublic class ApiExceptionHandler {\n\n @ExceptionHandler(BusinessException.class)\n public ResponseEntity handleBusiness(BusinessException ex,\n HttpServletRequest request) {\n log.warn(\"Business error: [{}] {} at {}\",\n ex.getErrorCode(), ex.getMessage(), request.getRequestURI());\n\n ApiError error = ApiError.builder()\n .code(ex.getErrorCode())\n .message(ex.getMessage())\n .path(request.getRequestURI())\n .timestamp(ex.getTimestamp())\n .details(ex.getContext())\n .build();\n\n return ResponseEntity\n .status(ex.getHttpStatus())\n .body(error);\n }\n\n @ExceptionHandler(TechnicalException.class)\n public ResponseEntity handleTechnical(TechnicalException ex,\n HttpServletRequest request) {\n String traceId = UUID.randomUUID().toString().substring(0, 8);\n log.error(\"Technical error [{}]: {} at {}\",\n traceId, ex.toString(), request.getRequestURI(), ex);\n\n ApiError error = ApiError.builder()\n .code(\"INTERNAL_ERROR\")\n .message(\"An unexpected error occurred. Reference: \" + traceId)\n .path(request.getRequestURI())\n .timestamp(Instant.now())\n .build();\n\n return ResponseEntity\n .status(HttpStatus.INTERNAL_SERVER_ERROR)\n .body(error);\n }\n\n @ExceptionHandler(MethodArgumentNotValidException.class)\n public ResponseEntity handleValidation(MethodArgumentNotValidException ex,\n HttpServletRequest request) {\n Map fieldErrors = ex.getBindingResult()\n .getFieldErrors()\n .stream()\n .collect(Collectors.toMap(\n FieldError::getField,\n fe -> fe.getDefaultMessage() != null ? fe.getDefaultMessage() : \"Invalid\",\n (e1, e2) -> e1 + \"; \" + e2\n ));\n\n log.warn(\"Validation error at {}: {}\", request.getRequestURI(), fieldErrors);\n\n ApiError error = ApiError.builder()\n .code(\"VALIDATION_ERROR\")\n .message(\"Validation failed\")\n .path(request.getRequestURI())\n .timestamp(Instant.now())\n .details(Map.of(\"fields\", fieldErrors))\n .build();\n\n return ResponseEntity\n .status(HttpStatus.BAD_REQUEST)\n .body(error);\n }\n\n @ExceptionHandler(Exception.class)\n public ResponseEntity handleUnexpected(Exception ex,\n HttpServletRequest request) {\n String traceId = UUID.randomUUID().toString().substring(0, 8);\n log.error(\"Unexpected error [{}] at {}\", traceId, request.getRequestURI(), ex);\n\n ApiError error = ApiError.builder()\n .code(\"INTERNAL_ERROR\")\n .message(\"An unexpected error occurred. Reference: \" + traceId)\n .path(request.getRequestURI())\n .timestamp(Instant.now())\n .build();\n\n return ResponseEntity\n .status(HttpStatus.INTERNAL_SERVER_ERROR)\n .body(error);\n }\n}\n\n@Builder\npublic record ApiError(\n String code,\n String message,\n String path,\n Instant timestamp,\n Map details\n) {\n public ApiError {\n details = details != null ? details : Map.of();\n }\n}\n```\n\n---\n\n### Exercise 3: Exception with Context\n⭐⭐ Difficulty: Medium | ⏱️ Time: 15 minutes\n\n**Task:** Create an exception that carries rich context for debugging.\n\n```java\n// Create PaymentFailedException that includes:\n// - Transaction ID\n// - Amount\n// - Gateway response code\n// - Retry suggestion\n// - Method for generating log-friendly message\n```\n\n**✅ Solution:**\n\n```java\npublic class PaymentFailedException extends BusinessException {\n private final String transactionId;\n private final BigDecimal amount;\n private final String gatewayCode;\n private final boolean retryable;\n\n public PaymentFailedException(Builder builder) {\n super(builder.message, \"PAYMENT_FAILED\", Map.of(\n \"transactionId\", builder.transactionId,\n \"amount\", builder.amount.toPlainString(),\n \"gatewayCode\", builder.gatewayCode,\n \"retryable\", builder.retryable\n ));\n this.transactionId = builder.transactionId;\n this.amount = builder.amount;\n this.gatewayCode = builder.gatewayCode;\n this.retryable = builder.retryable;\n }\n\n public String getTransactionId() { return transactionId; }\n public BigDecimal getAmount() { return amount; }\n public String getGatewayCode() { return gatewayCode; }\n public boolean isRetryable() { return retryable; }\n\n @Override\n public HttpStatus getHttpStatus() {\n return HttpStatus.PAYMENT_REQUIRED;\n }\n\n public String toLogMessage() {\n return String.format(\n \"Payment failed [txn=%s, amount=%s, code=%s, retryable=%s]: %s\",\n transactionId, amount, gatewayCode, retryable, getMessage()\n );\n }\n\n public static Builder builder(String transactionId) {\n return new Builder(transactionId);\n }\n\n public static class Builder {\n private final String transactionId;\n private String message = \"Payment processing failed\";\n private BigDecimal amount = BigDecimal.ZERO;\n private String gatewayCode = \"UNKNOWN\";\n private boolean retryable = false;\n\n public Builder(String transactionId) {\n this.transactionId = transactionId;\n }\n\n public Builder message(String message) {\n this.message = message;\n return this;\n }\n\n public Builder amount(BigDecimal amount) {\n this.amount = amount;\n return this;\n }\n\n public Builder gatewayCode(String gatewayCode) {\n this.gatewayCode = gatewayCode;\n return this;\n }\n\n public Builder retryable(boolean retryable) {\n this.retryable = retryable;\n return this;\n }\n\n public PaymentFailedException build() {\n return new PaymentFailedException(this);\n }\n }\n}\n\n// Usage\nthrow PaymentFailedException.builder(\"TXN-12345\")\n .message(\"Card declined by issuer\")\n .amount(new BigDecimal(\"99.99\"))\n .gatewayCode(\"DO_NOT_HONOR\")\n .retryable(false)\n .build();\n```\n\n---\n\n### Exercise 4: Exception Factory\n⭐⭐⭐ Difficulty: Medium-Hard | ⏱️ Time: 20 minutes\n\n**Task:** Create an exception factory with fluent API for common scenarios.\n\n```java\n// Factory should support:\n// throw Exceptions.notFound(User.class, userId);\n// throw Exceptions.conflict(\"email\", email);\n// throw Exceptions.validation().field(\"email\", \"Invalid\").field(\"age\", \"Required\").build();\n// throw Exceptions.external(\"PaymentGateway\", 503, cause);\n```\n\n**✅ Solution:**\n\n```java\npublic final class Exceptions {\n\n private Exceptions() {}\n\n // Not found\n public static EntityNotFoundException notFound(Class type, Object id) {\n return new EntityNotFoundException(type.getSimpleName(), id);\n }\n\n public static EntityNotFoundException notFound(String entity, Object id) {\n return new EntityNotFoundException(entity, id);\n }\n\n // Conflict\n public static ConflictException conflict(String field, Object value) {\n return new ConflictException(field, value);\n }\n\n // Validation builder\n public static ValidationBuilder validation() {\n return new ValidationBuilder();\n }\n\n // External service\n public static ExternalServiceException external(String service, int status, Throwable cause) {\n return new ExternalServiceException(service, status, cause);\n }\n\n public static ExternalServiceException external(String service, String message) {\n return new ExternalServiceException(service, message);\n }\n\n // Unauthorized/Forbidden\n public static UnauthorizedException unauthorized(String reason) {\n return new UnauthorizedException(reason);\n }\n\n public static ForbiddenException forbidden(String resource, String action) {\n return new ForbiddenException(resource, action);\n }\n\n // Validation builder\n public static class ValidationBuilder {\n private final List errors = new ArrayList<>();\n\n public ValidationBuilder field(String field, String message) {\n errors.add(new ValidationError(field, message));\n return this;\n }\n\n public ValidationBuilder field(String field, String message, Object value) {\n errors.add(new ValidationError(field, message, value));\n return this;\n }\n\n public ValidationBuilder addIf(boolean condition, String field, String message) {\n if (condition) {\n errors.add(new ValidationError(field, message));\n }\n return this;\n }\n\n public ValidationException build() {\n if (errors.isEmpty()) {\n throw new IllegalStateException(\"No validation errors added\");\n }\n return new ValidationException(errors);\n }\n\n public void throwIfErrors() {\n if (!errors.isEmpty()) {\n throw new ValidationException(errors);\n }\n }\n }\n}\n\n// Usage examples\nthrow Exceptions.notFound(User.class, 123L);\nthrow Exceptions.conflict(\"email\", \"user@example.com\");\n\nthrow Exceptions.validation()\n .field(\"email\", \"Invalid format\")\n .field(\"password\", \"Too short\")\n .addIf(age < 18, \"age\", \"Must be 18+\")\n .build();\n\nExceptions.validation()\n .addIf(name == null, \"name\", \"Required\")\n .addIf(email == null, \"email\", \"Required\")\n .throwIfErrors();\n```\n\n---\n\n### Exercise 5: Transactional Exception Handling\n⭐⭐⭐⭐ Difficulty: Hard | ⏱️ Time: 25 minutes\n\n**Task:** Design exception handling for a complex transactional operation with compensating actions.\n\n```java\n// Order processing that should:\n// 1. Create order\n// 2. Reserve inventory\n// 3. Process payment\n// 4. On payment failure → release inventory\n// 5. On any failure → mark order as failed\n// 6. Return appropriate error to client\n```\n\n**✅ Solution:**\n\n```java\n@Service\n@RequiredArgsConstructor\n@Slf4j\npublic class OrderProcessingService {\n\n private final OrderRepository orderRepository;\n private final InventoryService inventoryService;\n private final PaymentService paymentService;\n\n public OrderResult processOrder(OrderRequest request) {\n Order order = null;\n\n try {\n // Step 1: Create order\n order = createOrder(request);\n log.info(\"Order created: {}\", order.getId());\n\n // Step 2: Reserve inventory\n reserveInventory(order);\n log.info(\"Inventory reserved for order: {}\", order.getId());\n\n // Step 3: Process payment\n processPayment(order);\n log.info(\"Payment processed for order: {}\", order.getId());\n\n // Success\n order.setStatus(OrderStatus.CONFIRMED);\n orderRepository.save(order);\n\n return OrderResult.success(order.getId());\n\n } catch (InventoryException e) {\n // Inventory failed - mark order as failed\n handleFailure(order, OrderStatus.INVENTORY_FAILED, e);\n throw new OrderProcessingException(\n \"Items not available\", order, e);\n\n } catch (PaymentException e) {\n // Payment failed - compensate inventory\n compensateInventory(order);\n handleFailure(order, OrderStatus.PAYMENT_FAILED, e);\n throw new OrderProcessingException(\n \"Payment failed: \" + e.getReason(), order, e);\n\n } catch (Exception e) {\n // Unexpected error - attempt full compensation\n compensateFully(order);\n handleFailure(order, OrderStatus.FAILED, e);\n throw new OrderProcessingException(\n \"Order processing failed\", order, e);\n }\n }\n\n private Order createOrder(OrderRequest request) {\n Order order = new Order();\n order.setStatus(OrderStatus.PENDING);\n order.setItems(request.getItems());\n order.setCustomerId(request.getCustomerId());\n return orderRepository.save(order);\n }\n\n private void reserveInventory(Order order) {\n try {\n inventoryService.reserve(order.getItems());\n } catch (InsufficientStockException e) {\n throw new InventoryException(\"Insufficient stock\", e);\n }\n }\n\n private void processPayment(Order order) {\n try {\n paymentService.charge(order.getCustomerId(), order.getTotal());\n } catch (CardDeclinedException e) {\n throw new PaymentException(e.getReason(), e);\n }\n }\n\n private void compensateInventory(Order order) {\n if (order != null) {\n try {\n inventoryService.release(order.getItems());\n log.info(\"Inventory released for order: {}\", order.getId());\n } catch (Exception e) {\n log.error(\"Failed to release inventory for order: {}\",\n order.getId(), e);\n // Queue for manual review\n alertService.inventoryCompensationFailed(order, e);\n }\n }\n }\n\n private void compensateFully(Order order) {\n // Release inventory and refund if needed\n compensateInventory(order);\n // Payment might need refund depending on state\n }\n\n private void handleFailure(Order order, OrderStatus status, Exception cause) {\n if (order != null) {\n order.setStatus(status);\n order.setFailureReason(cause.getMessage());\n orderRepository.save(order);\n }\n }\n}\n\npublic class OrderProcessingException extends BusinessException {\n private final Order order;\n\n public OrderProcessingException(String message, Order order, Throwable cause) {\n super(message, \"ORDER_PROCESSING_FAILED\",\n order != null ? Map.of(\"orderId\", order.getId()) : Map.of());\n this.order = order;\n initCause(cause);\n }\n\n @Override\n public HttpStatus getHttpStatus() {\n return HttpStatus.UNPROCESSABLE_ENTITY;\n }\n}\n```\n\n---\n\n## 🎤 Interview Questions\n\n### Q1: Checked vs Unchecked exceptions - when to use each?\n\n**Answer:**\n- **Checked**: Recoverable conditions, caller CAN and SHOULD handle (IOException, SQLException)\n- **Unchecked**: Programming errors or unrecoverable (NullPointerException, IllegalArgumentException)\n\nModern practice: Prefer unchecked for most cases, as checked exceptions:\n- Clutter method signatures\n- Often caught and wrapped anyway\n- Don't work with lambdas/streams\n\n### Q2: How do you design exception hierarchy for an application?\n\n**Answer:**\n1. Create base `ApplicationException` with common fields (code, context, timestamp)\n2. Split into `BusinessException` (4xx, user-facing) and `TechnicalException` (5xx, logged)\n3. Create domain-specific exceptions (OrderException, PaymentException)\n4. Use factory methods for consistent creation\n5. Integrate with global handler for uniform API responses\n\n---\n\n## 📝 Summary\n\n| Type | Purpose | HTTP Status | Log Level |\n|------|---------|-------------|-----------|\n| BusinessException | User can fix | 4xx | WARN |\n| ValidationException | Invalid input | 400 | WARN |\n| NotFoundException | Resource missing | 404 | WARN |\n| TechnicalException | System issue | 5xx | ERROR |\n\n---\n\n## 📅 Review Schedule for This Article\n\n| Day | Task | Time |\n|-----|------|------|\n| Day 1 | Review exception hierarchy mental model diagram | 5 min |\n| Day 3 | Redo Exercise 1 (Design Exception Hierarchy) | 15 min |\n| Day 7 | Answer interview questions without looking | 10 min |\n| Day 14 | Redo Debug This (Swallowed Exception) | 15 min |\n| Day 30 | Audit exception handling in one service of your codebase | 20 min |\n\n---\n\n*Next: [Part 15: Result Pattern]*\n","featuredImage","isPublished","isFeatured","subscriptionType","BASIC","publishedAt","2026-06-10T07:19:24.808294Z","createdAt","2026-06-10T07:19:24.809169Z","updatedAt","2026-06-16T21:26:56.086200Z","readingTimeMinutes",17,"estimatedReadingTime","authorId",3,"authorUsername","tomasz_main","categoryName","Java","readingTime","seriesId","seriesOrder",14,"author",{"_31":55,"_98":57,"_99":100,"_101":102,"_103":-5,"_104":-5,"_105":-5,"_106":-5,"_107":-5},"category",{"_31":94,"_72":59,"_35":95,"_75":96,"_97":-5},"tags",[78,79,80,81],"series",{"_31":16,"_72":73,"_35":74,"_75":76,"_77":23},"name","Advanced Clean Code Patterns: From Principles to Production Mastery","advanced-clean-code-patterns","description","A comprehensive 26-part series covering enterprise-grade clean code patterns for Java developers. From SOLID principles and code smells through refactoring patterns, error handling, validation, to legacy modernization and modern Java 21+ features. Includes real production stories, mental models, exercises, and 150+ interview questions.","isActive",{"_31":91,"_72":92,"_35":93},{"_31":88,"_72":89,"_35":90},{"_31":85,"_72":86,"_35":87},{"_31":82,"_72":83,"_35":84},70,"Exception Hierarchy","exception-hierarchy",68,"Exception Handling","exception-handling",71,"Error Handling","error-handling",69,"Custom Exceptions","custom-exceptions",5,"java","Category for Java","colorHex","username","firstName","Tomasz","lastName","Jarosz","profilePicture","bio","website","githubUrl","linkedinUrl"]