¿Cómo Implementar el Manejo de Excepciones con Spring para una API REST?

En esta entrada, exploraremos cómo implementar el manejo de excepciones con Spring para una API REST. Aprenderemos que existen varias posibilidades para hacerlo, todas enfocadas en lograr una excelente separación de preocupaciones. La aplicación puede lanzar excepciones de manera normal para indicar algún tipo de falla, que después se manejará por separado.

¿Por qué es importante manejar excepciones en APIs REST?

Cuando se desarrolla una API REST, es crucial tener un manejo adecuado de errores. Esto no solo mejora la experiencia del usuario, sino que también ayuda a los desarrolladores a diagnosticar y resolver problemas en sus aplicaciones. Al implementar un manejo de excepciones eficaz, se puede enviar un mensaje claro sobre lo que salió mal, lo que facilita la identificación de problemas y la mejora de la calidad del software.

1. Resumen

Esta guía detallada cubrirá diversas estrategias para manejar excepciones en una API REST utilizando Spring, centrándonos en dos enfoques clave: el manejo local de excepciones a nivel de controlador y el manejo global de excepciones mediante clases de asesoramiento de controladores (@ControllerAdvice). Veremos ejemplos en código para ilustrar cómo implementar cada enfoque.

1.1. ¿Qué son las Excepciones en Spring?

Las excepciones en Spring son situaciones que pueden surgir en el contexto de una aplicación. El objetivo del manejo de excepciones es asegurarse de que las excepciones sean devueltas de manera adecuada y entendible por el cliente de la API.

@ExceptionHandler

Podemos usar @ExceptionHandler para anotar métodos que Spring invocará automáticamente cuando ocurra la excepción especificada. Hay dos maneras de especificar la excepción: mediante la anotación o declarándola como un parámetro del método, lo que nos permite leer detalles del objeto de la excepción para manejarla correctamente.

2.1. Ejemplo básico de manejo de excepciones

Un manejador de excepciones básico que devuelve un código de estado 400 podría ser:

@ResponseStatus(HttpStatus.BAD_REQUEST)
@ExceptionHandler(CustomException1.class)
public void handleException1() {
    // Este método podría contener lógica adicional
}

2.2. Manejo de excepciones con detalles

También podemos declarar la excepción manejada como un parámetro del método para obtener detalles y crear un objeto de problemas que sea compatible con RFC-9457:

@ResponseStatus(HttpStatus.BAD_REQUEST)
@ExceptionHandler
public ProblemDetails handleException2(CustomException2 ex) {
    // Lógica para crear un objeto ProblemDetails
    return new ProblemDetails("Los detalles del problema...");
}

A partir de Spring 6.2, podemos escribir diferentes manejadores de excepciones para diferentes tipos de contenido, como se muestra a continuación:

@ResponseStatus(HttpStatus.BAD_REQUEST)
@ExceptionHandler(produces = MediaType.APPLICATION_JSON_VALUE)
public CustomExceptionObject handleException3Json(CustomException3 ex) {
    // Lógica para manejar excepciones y devolver respuesta JSON
}

@ResponseStatus(HttpStatus.BAD_REQUEST)
@ExceptionHandler(produces = MediaType.TEXT_PLAIN_VALUE)
public String handleException3Text(CustomException3 ex) {
    return "Error en formato de texto plano";
}

3. Manejo de Excepciones Local (Nivel de Controlador)

Podemos colocar estos métodos manejadores en la clase del controlador. Utilizando esta aproximación, el enfoque se limita a un solo controlador:

@RestController
public class FooController {
    // Métodos de controlador...

    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @ExceptionHandler(CustomException1.class)
    public void handleException() {
        // Manejo específico
    }
}

3.1. Desventajas del manejo local

El problema de este enfoque es que no se puede usar en múltiples controladores a menos que se coloque en una clase base y se utilice herencia, lo que a menudo no es deseable.

4. Manejo de Excepciones Global

Para manejar una excepción particular en todos los controladores de la aplicación, podemos escribir una clase simple que use @ControllerAdvice, la cual contiene código compartido entre múltiples controladores:

@RestControllerAdvice
public class MyGlobalExceptionHandler {
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @ExceptionHandler(CustomException1.class)
    public void handleException() {
        // Lógica de manejo de excepciones global
    }
}

También tenemos la opción de heredar de ResponseEntityExceptionHandler, lo que proporciona funcionalidad común predefinida:

@ControllerAdvice
public class MyCustomResponseEntityExceptionHandler extends ResponseEntityExceptionHandler {
    @ExceptionHandler({ 
        IllegalArgumentException.class, 
        IllegalStateException.class 
    })
    ResponseEntity