Gestión global de excepciones con @ControllerAdvice
Centralice la gestión de excepciones de todos los controladores con @ExceptionHandler y @ControllerAdvice.
Gestión global de excepciones con @ControllerAdvice es una lección gratuita de Java Academy en CoddyKit. Esta es la lección 3 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Java Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Java Academy incluye 4 lecciones en total.
El problema de no contar con gestión global
Sin una gestión global de excepciones, cada método del controlador necesita bloques try-catch, se duplica la construcción de respuestas de error y los detalles de las excepciones pueden filtrarse a los clientes.
@ControllerAdvice y @RestControllerAdvice
@ControllerAdvice define una clase global para gestionar excepciones. @RestControllerAdvice añade @ResponseBody, de modo que todos los métodos gestores devuelven JSON automáticamente.
@RestControllerAdvice
public class GlobalExceptionHandler {
// @ExceptionHandler methods go here
}Métodos @ExceptionHandler
Anote un método con @ExceptionHandler(ExceptionType.class). Spring dirige al método las excepciones de ese tipo y de sus subclases. Devuelva un ResponseEntity con el estado adecuado.
@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {
return ResponseEntity.status(HttpStatus.NOT_FOUND)
.body(new ErrorResponse("NOT_FOUND", ex.getMessage()));
}Gestionar varios tipos de excepciones
Enumere varios tipos de excepciones en un mismo gestor o utilice una clase base común. Spring elige el gestor más específico disponible.
@ExceptionHandler({IllegalArgumentException.class, IllegalStateException.class})
public ResponseEntity<ErrorResponse> handleBadRequest(RuntimeException ex) {
return ResponseEntity.badRequest()
.body(new ErrorResponse("BAD_REQUEST", ex.getMessage()));
}Gestionar errores de validación
Capture MethodArgumentNotValidException para extraer los errores a nivel de campo de los cuerpos de solicitud validados con @Valid.
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<Map<String, Object>> handleValidation(MethodArgumentNotValidException ex) {
Map<String, String> fieldErrors = new LinkedHashMap<>();
ex.getBindingResult().getFieldErrors().forEach(e ->
fieldErrors.put(e.getField(), e.getDefaultMessage()));
return ResponseEntity.badRequest()
.body(Map.of("errors", fieldErrors, "status", 400));
}Gestionar infracciones de restricciones
ConstraintViolationException se lanza al validar parámetros de métodos con @Validated en la capa de servicio. Gestiónela por separado de los errores de validación de MVC.
@ExceptionHandler(ConstraintViolationException.class)
public ResponseEntity<Map<String, String>> handleConstraint(ConstraintViolationException ex) {
Map<String, String> errors = new LinkedHashMap<>();
ex.getConstraintViolations().forEach(v ->
errors.put(v.getPropertyPath().toString(), v.getMessage()));
return ResponseEntity.badRequest().body(errors);
}Acceder a HttpServletRequest
Añada HttpServletRequest como parámetro para obtener detalles de la solicitud (URL, método y cabeceras) con fines de registro o para incluirlos en la respuesta de error.
@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleAll(Exception ex, HttpServletRequest req) {
log.error("Unhandled error on {} {}", req.getMethod(), req.getRequestURI(), ex);
return ResponseEntity.internalServerError()
.body(new ErrorResponse("INTERNAL_ERROR", "Unexpected error"));
}@ResponseStatus en las clases de excepciones
Anote las clases de excepciones personalizadas con @ResponseStatus para establecer automáticamente el estado HTTP sin un método gestor; es una opción más sencilla para casos básicos.
@ResponseStatus(HttpStatus.NOT_FOUND)
public class ResourceNotFoundException extends RuntimeException {
public ResourceNotFoundException(String msg) { super(msg); }
}Limitar el alcance de @ControllerAdvice
Restrinja el advice a paquetes, anotaciones o clases base específicos mediante los atributos de @ControllerAdvice.
@RestControllerAdvice(basePackages = "com.example.api")
public class ApiExceptionHandler { ... }
@RestControllerAdvice(assignableTypes = {UserController.class, OrderController.class})
public class SpecificHandler { ... }Registrar excepciones en los gestores
Registre las excepciones con el nivel adecuado: los errores del usuario (4xx) en WARN y los errores inesperados (5xx) en ERROR, incluyendo el stack trace completo.
@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleAll(Exception ex, HttpServletRequest req) {
if (ex instanceof BusinessException) log.warn("Business error: {}", ex.getMessage());
else log.error("Unexpected error on {}", req.getRequestURI(), ex);
return ...
}Prioridad de los controladores de excepciones
Spring selecciona el controlador más específico. Si ResourceNotFoundException extends RuntimeException, un controlador para ResourceNotFoundException tiene prioridad sobre uno para RuntimeException.
Comprobación rápida
¿Qué anotación marca un método para gestionar globalmente un tipo de excepción específico?
Resumen
Utilice @RestControllerAdvice + @ExceptionHandler para centralizar la gestión de errores. Devuelva ResponseEntity con una estructura de error coherente. Gestione por separado la validación (MethodArgumentNotValidException) y las restricciones (ConstraintViolationException). Registre los errores 4xx como WARN y los 5xx como ERROR.
Preguntas frecuentes
¿La lección «Gestión global de excepciones con @ControllerAdvice» es gratis?
Sí — el texto completo de «Gestión global de excepciones con @ControllerAdvice» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Java Academy, actualiza a CoddyKit PRO. El curso de Java Academy incluye 4 lecciones en total.
¿Qué aprenderé en «Gestión global de excepciones con @ControllerAdvice»?
Centralice la gestión de excepciones de todos los controladores con @ExceptionHandler y @ControllerAdvice. Practicas Java Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar Java Academy?
No se requiere experiencia previa. Java Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 3 de 4.
¿Cuánto tiempo toma la lección «Gestión global de excepciones con @ControllerAdvice»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de Java Academy?
Sí. Cada lección de Java Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Validación de beans: @NotNull, @Size, @Pattern
- Anotaciones de restricciones personalizadas
- Gestión global de excepciones con @ControllerAdvice
- Detalles de problemas RFC 7807 y respuestas de error coherentes