En una aplicación Spring Boot, manejar errores de forma consistente puede volverse complicado cuando tenemos muchos controladores. Para evitar repetir lógica de manejo de excepciones en cada uno, Spring nos ofrece una poderosa anotación: @ControllerAdvice.
@ControllerAdvice es una anotación que permite manejar excepciones globalmente en todos los controladores (@Controller o @RestController).
Funciona como un interceptor de excepciones lanzadas por los controladores y te permite centralizar la lógica de manejo de errores.
Se usa comúnmente junto con @ExceptionHandler para capturar tipos específicos de excepciones.
Supongamos que tenemos un controlador que lanza una excepción cuando un recurso no se encuentra:
@RestController
@RequestMapping("/api/users")
public class UserController {
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
if (id == 1) {
return new User(1L, "Alice");
}
throw new UserNotFoundException("User not found with id: " + id);
}
}
Y defines la excepción personalizada:
public class UserNotFoundException extends RuntimeException {
public UserNotFoundException(String message) {
super(message);
}
}
Ahora puedes manejar esta excepción de forma global con @ControllerAdvice:
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(UserNotFoundException.class)
public ResponseEntity<Map<String, String>> handleUserNotFound(UserNotFoundException ex) {
Map<String, String> response = new HashMap<>();
response.put("error", ex.getMessage());
return ResponseEntity.status(HttpStatus.NOT_FOUND).body(response);
}
@ExceptionHandler(Exception.class)
public ResponseEntity<Map<String, String>> handleGeneral(Exception ex) {
Map<String, String> response = new HashMap<>();
response.put("error", "Internal Server Error");
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(response);
}
}
@ControllerAdvice se aplica a todos los controladores por defecto, pero también puede limitarse a un paquete o anotación específica:
@ControllerAdvice(basePackages = "com.example.api")
@ExceptionHandler indica qué tipo de excepción manejar.
Los métodos pueden devolver cualquier tipo de objeto compatible con Spring MVC: ResponseEntity, ModelAndView, o incluso un String.
Entre las ventajas tenemos:
- Centraliza el manejo de errores.
- Evita duplicación de código en controladores.
- Facilita la personalización de las respuestas HTTP.
- Permite diferenciar entre distintos tipos de errores.
Si tu aplicación es una API REST, puedes usar: @RestControllerAdvice
Esta versión combina @ControllerAdvice con @ResponseBody, lo que simplifica el retorno de respuestas JSON automáticamente (sin necesidad de ResponseEntity explícito).
Veamos un ejemplo:
@RestControllerAdvice
public class ApiExceptionHandler {
@ExceptionHandler(UserNotFoundException.class)
public Map<String, String> handleUserNotFound(UserNotFoundException ex) {
return Map.of("error", ex.getMessage());
}
}
@ControllerAdvice es una herramienta esencial para crear APIs limpias, consistentes y fáciles de mantener en Spring Boot.
Al centralizar el manejo de excepciones, podés mejorar la legibilidad del código y ofrecer respuestas coherentes a los clientes.
.jpeg)
