Esta guía pretende informar sobre las buenas prácticas a la hora de devolver mensajes de error en APIs REST con FundeWebJS, así como enumerar los mecanismos que proprociona Spring Boot para configurar y manejar estos errores.
Esta página es la equivalente FundeWebJS a la Wiki Manejo de errores en servicios REST de FundeWeb.
La integración con el estándar RFC 7807 Problem Details for HTTP APIs, no se incluye por defecto en Spring Boot pero se encuentra en proceso de desarrollo por parte de MNCS.
Buenas Prácticas
Las principales indicaciones a la hora de construir una respuesta en un servicio REST (tanto para éxito como para error) son:
Usar la clase ResponseEntity<T> ( org.springframework.http.ResponseEntity) para envolver la respuesta.
Usar los códigos de estado de HTTP para indicar el resultado de la petición.
No es necesario conocer ni utilizar todos los códigos de estado HTTP.
Este es el subconjunto de códigos de estado aconsejado para cada situación:
200 - Sólo utilizar en caso de RESPUESTA CORRECTA. No debe utilizarse cuando ocurre un error.
400 - Mensaje mal formado, petición o url incorrecta.
401 - Fallo de autenticación.
403 - Acceso no permitido a un recurso.
404 - Recurso no encontrado.
405 - Método HTTP (GET, POST, PUT…) no permitido.
406 - MediaType solicitado no soportado (Accept en la petición y Produces del servicio no concuerdan).
415 - ContentType enviado no soportado (ContentType en la petición y Consumes del servicio no concuerdan).
500 - Error general en el servidor.
503 - Servidor no disponible temporalmente.
La clase ResponseEntity proporciona varios métodos estáticos y builders para construir la respuesta en nuestros endpoints en base a estos códigos de forma muy rápida.
Es aconsejable usar estos códigos de estado HTTP mediante el enumerado org.springframework.http.HttpStatus.
Guía detallada
Spring Boot proporciona varios mecanismos para capturar excepciones (global o localmente) y devolver mensajes de error (estándar o personalizados). Estos mecanismos han ido evolucionando con las diversas versiones del framework y, en algunos casos, pueden llegar a solaparse.
El término "modelo de respuesta" empleado en esta guía se refiere al formato de JSON (los campos) devuelto cuando sucede una situación de error.
La integración con el estándar RFC 7807 Problem con Spring Boot está en desarrollo. Cuando esté terminada dicha integración se modificará el modelo de respuesta estándar para contener los campos del RFC Problem (ver wiki manejo de errores en FundeWeb).
Ante cualquier duda póngase en contacto con MNCS.
A continuación se va a explicar estos mecanismos desde el enfoque de los casos de uso más habituales:
ResponseStatusException => Devolver modelo de respuesta estándar de forma rápida y correcta .
DefaultErrorAttributes => Modificar el modelo de respuesta de forma global.
ExceptionHandler => Manejar localmente una excepción propia y devolver el modelo de respuesta estándar o un modelo propio.
ControllerAdvice => Manejar de forma global todas mis excepciones y devolver el modelo de respuesta estándar o un modelo propio.
ControllerAdvice + ResponseEntityExceptionHandler => Modificar el comportamiento y el modelo de respuesta para excepciones internas capturadas por Spring Boot.
[EXTRA] Bean Validation => Modificar la respuesta si se usa para validar parámetros.
1. ResponseStatusException
Útil para devolver un error de forma correcta y rápida, sin preocuparnos de los datos devueltos.
Se construye la excepción pasándole el status code HTTP de error deseado y Spring Boot la captura y maneja de forma automática.
Devuelve el modelo de respuesta estándar (ver siguiente apartado).
Ventajas: rápido, status code parametrizable.
Desventajas: Modelo de respuesta fijo.
Ejemplo:
try{
.....
throw new TestException( HttpStatus.BAD_REQUEST,"2. ResponseStatusException con FundeWebJSErrorAttributtes" );
.....
} catch ( final TestException e2 ) {
//Se captura una excepción existente y se lanza una nueva ResponseStatusException
log.error( "Test de prueba de ResponseStatusException con custom FundeWebJSErrorAttributtes: {}",e2.getMessage() );
throw new ResponseStatusException( HttpStatus.INTERNAL_SERVER_ERROR, e2.getMessage(),e2.getCause() );
} ....
Fuente: Rest handleError (https://gitlab.um.es/mncs/fundewebjsshowcase-api/-/blob/desarrollo/src/main/java/es/um/atica/fundewebjsshowcasebackend/services/rest/impl/RestTestImpl.java).
Petición:
https://fundewebjsshowcasedesa.um.es/api/v1.0/public/handleError/5
Respuesta:
{
"fecha": "05/10/2021 10:31:27",
"estado": "INTERNAL_SERVER_ERROR",
"mensaje": "2. ResponseStatusException con FundeWebJSErrorAttributtes",
"tipoRespuesta": "CUSTOM_DefaultErrorAttributes"
}
1.1 ResponseStatus:
La excepción ResponseStatusException es una evolución de otro mecanismo, la notación @ResponseStatus .
Por comodidad se recomienda usar ResponseStatusException, pero es posible seguir usando esta notación declarándola nuestras excepciones y lanzándolas desde nuestra API REST directamente.
Ver: Ejemplo ResponseStatus (https://gitlab.um.es/mncs/fundewebjsshowcase-api/-/blob/desarrollo/src/main/java/es/um/atica/fundewebjsshowcasebackend/exceptions/TestResponseStatusException.java).
Ejemplo ejecución:
...
@ResponseStatus( code = HttpStatus.BAD_REQUEST, reason = "Reason en ResponseStatus", value = HttpStatus.INTERNAL_SERVER_ERROR )
public class TestResponseStatusException extends RuntimeException
....
/
try{
...
throw new TestResponseStatusException( HttpStatus.BAD_REQUEST, "1. Notación ResponseStatus con FundeWebJSErrorAttributtes" );
...
} catch ( final TestResponseStatusException e1 ) {
log.error( "Test de prueba de notación @ResponseStatus con custom FundeWebJSErrorAttributtes: {}",e1.getMessage() );
throw e1;
}
...
https://fundewebjsshowcasedesa.um.es/api/v1.0/public/handleError/1
{
"fecha": "05/10/2021 10:45:25",
"estado": "BAD_REQUEST",
"mensaje": "1. Notación ResponseStatus con FundeWebJSErrorAttributtes",
"tipoRespuesta": "CUSTOM_DefaultErrorAttributes"
}
2. DefaultErrorAttributes
Por defecto Spring usa el modelo de respuesta (los campos que se devuelven) devuelto por la clase DefaultErrorAttributes.
Podemos modificar el modelo de respuesta estándar extendiendo esta clase (y anotándola con @Component).
Cambiar el modelo de respuesta implica que, si no se usa otro mecanismo, el nuevo modelo será devuelto en todas las situaciones de error.
Ejemplo de fichero extendido:
@Component
public class FundeWebJSErrorAttributes extends DefaultErrorAttributes {
private static final org.apache.logging.log4j.Logger log = org.apache.logging.log4j.LogManager
.getLogger( FundeWebJSErrorAttributes.class );
public static final String TIPO_RESPUESTA = "CUSTOM_DefaultErrorAttributes";
@Override
public Map<String, Object> getErrorAttributes( WebRequest webRequest, boolean includeStackTrace ) {
final Map<String, Object> allErrorAttributes = super.getErrorAttributes( webRequest, includeStackTrace );
final Map<String, Object> errorAttributes = new HashMap<>();
final int statusCode = ( int ) allErrorAttributes.get( "status" );
errorAttributes.put( "tipoRespuesta", TIPO_RESPUESTA );
errorAttributes.put( "estado", HttpStatus.valueOf( statusCode ) );
errorAttributes.put( "fecha",
LocalDateTime.now().format( DateTimeFormatter.ofPattern( "dd/MM/yyyy HH:mm:ss" ) ) );
String mensaje = "";
final Throwable throwable = getError( webRequest );
if ( throwable instanceof ResponseStatusException ) {
final ResponseStatusException responseStatusException = ( ResponseStatusException ) throwable;
mensaje = responseStatusException.getReason() == null ? "" : responseStatusException.getReason();
} else if ( throwable instanceof ConstraintViolationException ) {
webRequest.setAttribute( "status", HttpStatus.BAD_REQUEST.value(), 1 );
errorAttributes.put( "estado", HttpStatus.BAD_REQUEST.toString() );
mensaje = throwable.getMessage() == null ? "" : throwable.getMessage();
} else {
if ( ( throwable != null ) && ( throwable.getMessage() != null ) ) {
mensaje = throwable.getMessage() == null ? "" : throwable.getMessage();
}
}
errorAttributes.put( "mensaje", mensaje );
return errorAttributes;
}
}
Fuente: FundeWebJSErrorAttributes.java
No se recomienda desarrollar modelos propios de respuesta estándar hasta que se complete la integración con el RFC 7807 Problem Details for HTTP APIs por parte de MNCS.
3. ExceptionHandler
En los métodos anteriores se ha explicado cómo lanzar excepciones en nuestros servicios y modificar el modelo de respuesta.
A partir de este punto se explicará cómo maneja Spring las excepciones y cómo modificar este mecanismo, lo que permitirá gestionar las respuestas, definir modelos de respuesta diferentes dependiendo de cada excepción, y sobreescribir el comportamiento estándar en situaciones de error no controladas.
Como primera aproximación a este enfoque tenemos la notación @ExceptionHandler.
Ventajas: Permite manejar una excepción y modificar los valores de la respuesta http así como el modelo.
Desventajas: solo funciona de forma local en el controlador REST donde se haya definido.
Ejemplo de uso: Para probarlo simplemente se define un POJO con los datos para el body de la respuesta, se crea el método anotado con ExceptionHandler y se lanza la excepción a capturar.
@Data
@RequiredArgsConstructor
@AllArgsConstructor
@Builder
public class TestLocalHandlerError {
@NonNull
private HttpStatus estado;
@JsonFormat(shape = Shape.STRING, pattern = "dd/MM/yyyy hh:mm:ss")
private LocalDateTime fecha;
@NonNull
private String mensaje;
@Builder.Default
private String tipoRespuesta = "CUSTOM_LocalHandler";
}
Fuente: TestLocalHandlerError.java (https://gitlab.um.es/mncs/fundewebjsshowcase-api/-/blob/desarrollo/src/main/java/es/um/atica/fundewebjsshowcasebackend/error/TestLocalHandlerError.java)
@ExceptionHandler( TestLocalHandlerException.class )
public ResponseEntity<TestLocalHandlerError> handleTestLocalHandler( TestLocalHandlerException ex ) {
final TestLocalHandlerError error = TestLocalHandlerError.builder()
.estado( HttpStatus.INTERNAL_SERVER_ERROR ).fecha( LocalDateTime.now() )
.mensaje( ex.getMessage() ).build();
return ResponseEntity.status( HttpStatus.INTERNAL_SERVER_ERROR ).body( error );
}
Fuente: Rest Controller Test (https://gitlab.um.es/mncs/fundewebjsshowcase-api/-/blob/desarrollo/src/main/java/es/um/atica/fundewebjsshowcasebackend/services/rest/impl/RestTestImpl.java)
...
try{
throw new TestLocalHandlerException("3. Excepción con handler local y modelo custom TestLocalHandlerError" );
} catch ( final TestLocalHandlerException e3 ) {
log.error( "Test de prueba de excepción con handler en el propio controller y modelo TestLocalHandlerError: {}", e3.getMessage() );
throw e3;
}
...
Ejemplo llamada:
https://fundewebjsshowcasedesa.um.es/api/v1.0/public/handleError/3
{
"estado": "INTERNAL_SERVER_ERROR",
"fecha": "05/10/2021 12:37:46",
"mensaje": "3. Excepción con handler local y modelo custom TestLocalHandlerError",
"tipoRespuesta": "CUSTOM_LocalHandler"
}
4. ControllerAdvice
El principal inconveniente del mecanismo anterior es que, si queremos manejar la misma excepción en varios controllers, habría que escribir el mismo método en cada uno de ellos.
La forma de manejar todas las expeciones de forma global y conjunta en toda nuestra aplicación se realiza a través de la notación @RestControllerAdvice.
La notación RestControllerAdvice engloba las notaciones ControllerAdvice (que registra la clase en el contexto de Spring para que pueda acceder a todos los controllers) y ResponseBody (para que los pojos enviados en la respuesta se interpreten como JSON).
Es posible declarar varios RestControllerAdvice para dividir el manejo de excepciones por paquetes, clases, anotaciones, etc.
Por defecto, si no se pasan parámetros en la declaración de la notación @RestControllerAdvice, los manejadores serán comunes a toda la aplicación.
Ejemplo de uso:
public class TestControllerAdviceException extends RuntimeException {
private static final long serialVersionUID = 1L;
public TestControllerAdviceException( String msg ) {
super( msg );
}
}
Fuente: TestControllerAdviceException.java (https://gitlab.um.es/mncs/fundewebjsshowcase-api/-/blob/desarrollo/src/main/java/es/um/atica/fundewebjsshowcasebackend/exceptions/TestControllerAdviceException.java)
@Data
@RequiredArgsConstructor
@AllArgsConstructor
@Builder
public class TestControllerAdviceError {
@Nonnull
private HttpStatus estado;
@JsonFormat(shape = Shape.STRING, pattern = "dd/MM/yyyy hh:mm:ss")
private LocalDateTime fecha;
@Nonnull
private String mensaje;
@Builder.Default
private String tipoRespuesta = "CUSTOM_ControllerAdvice";
private List<String> erroresValidacion;
}
Fuente: TestControllerAdviceError.java (https://gitlab.um.es/mncs/fundewebjsshowcase-api/-/blob/desarrollo/src/main/java/es/um/atica/fundewebjsshowcasebackend/error/TestControllerAdviceError.java)
@RestControllerAdvice( basePackages = "es.um.atica.fundewebjsshowcasebackend" )
public class TestControllerAdvice {
/**
* Handler de TestControllerAdviceException
*
* @param ex
* @return
* @see TestControllerAdviceException
* @see RestTestImpl
*/
@ExceptionHandler( TestControllerAdviceException.class )
public ResponseEntity<TestControllerAdviceError> handleTestControllerAdvice( TestControllerAdviceException ex ) {
final TestControllerAdviceError error = TestControllerAdviceError.builder()
.estado( HttpStatus.INTERNAL_SERVER_ERROR ).fecha( LocalDateTime.now() ).mensaje( ex.getMessage() )
.build();
return ResponseEntity.status( HttpStatus.INTERNAL_SERVER_ERROR ).body( error );
}}
Fuente: TestControllerAdvice.java (https://gitlab.um.es/mncs/fundewebjsshowcase-api/-/blob/desarrollo/src/main/java/es/um/atica/fundewebjsshowcasebackend/handler/TestControllerAdvice.java)
try{
...
throw new TestControllerAdviceException("4. Excepción con ControllerAdvice y modelo custom TestControllerAdviceError" );
...
} catch ( final TestControllerAdviceException e4 ) {
log.error("Test de prueba de excepción con handler en el ControllerAdvice y modelo TestControllerAdviceError: {}", e4.getMessage() );
throw e4;
}
Fuente: Rest Controller Test (https://gitlab.um.es/mncs/fundewebjsshowcase-api/-/blob/desarrollo/src/main/java/es/um/atica/fundewebjsshowcasebackend/services/rest/impl/RestTestImpl.java)
Ejemplo de petición:
https://fundewebjsshowcasedesa.um.es/api/v1.0/public/handleError/4
{
"estado": "INTERNAL_SERVER_ERROR",
"fecha": "05/10/2021 01:37:25",
"mensaje": "4. Excepción con ControllerAdvice y modelo custom TestControllerAdviceError",
"tipoRespuesta": "CUSTOM_ControllerAdvice",
"erroresValidacion": null
}
5. ControllerAdvice + ResponseEntityExceptionHandler
Según la documentación de Spring, existe una clase que proporciona un manejo centralizado de todas las excepciones en métodos anotados con @RequestMapping a través de la notación @ExceptionHandler. Se trata de la clase ResponseEntityExceptionHandler.
Es decir, si queremos usar nuestro ControllerAdvice declarado en el ejemplo anterior, y ampliarlo para modificar las respuestas en toda tipo de excepciones (internas o propias), solo tenemos que extender la clase ResponseEntityExceptionHandler.
En esta URL puede verse la lista de excepciones manejadas en esta clase => SPRING ResponseEntityExceptionHandler.
Así pues, el ejemplo del apartado anterior puede ampliarse para sobreescribir el ejemplo más típico, el método handleExceptionInternal, que termina siendo invocado por el resto de handlers.
@RestControllerAdvice( basePackages = "es.um.atica.fundewebjsshowcasebackend" )
public class TestControllerAdvice extends ResponseEntityExceptionHandler {
/**
* Handler de TestControllerAdviceException
*
* @param ex
* @return
* @see TestControllerAdviceException
* @see RestTestImpl
*/
@ExceptionHandler( TestControllerAdviceException.class )
public ResponseEntity<TestControllerAdviceError> handleTestControllerAdvice( TestControllerAdviceException ex ) {
final TestControllerAdviceError error = TestControllerAdviceError.builder()
.estado( HttpStatus.INTERNAL_SERVER_ERROR ).fecha( LocalDateTime.now() ).mensaje( ex.getMessage() )
.build();
return ResponseEntity.status( HttpStatus.INTERNAL_SERVER_ERROR ).body( error );
}
@Override
protected ResponseEntity<Object> handleExceptionInternal( Exception ex, @Nullable Object body, HttpHeaders headers,
HttpStatus status, WebRequest request ) {
if ( HttpStatus.INTERNAL_SERVER_ERROR.equals( status ) ) {
request.setAttribute( WebUtils.ERROR_EXCEPTION_ATTRIBUTE, ex, RequestAttributes.SCOPE_REQUEST );
}
return new ResponseEntity<>( body, headers, status );
}
}
Fuente: TestControllerAdvice.java (https://gitlab.um.es/mncs/fundewebjsshowcase-api/-/blob/desarrollo/src/main/java/es/um/atica/fundewebjsshowcasebackend/handler/TestControllerAdvice.java)
6. Bean Validation
Si estamos utilizando el estándar Bean Validation para realizar la validación de parámetros (path o request), posiblemente queramos capturar la excepción lanzada automáticamente para cambiar el mensaje (para incluir los errores de validación) y el código de respuesta HTTP (para devolver un 400 Bad Request en lugar de un 500).
La opción recomendada para manejar esta situación es añadir un ExceptionHandler en nuestro ControllerAdvice (ver ejemplo 4).
Ejemplo de uso:
/**
* Anotaciones Min y Max para validar el párametro Path de entrada "ex".
*/
@Override
public ResponseEntity<Object> handleError( HttpServletRequest request, HttpSession session,
@PathVariable( required = true ) @Min( 1 ) @Max( 4 ) Integer ex ) {...
}
Fuente: Rest Controller Test (https://gitlab.um.es/mncs/fundewebjsshowcase-api/-/blob/desarrollo/src/main/java/es/um/atica/fundewebjsshowcasebackend/services/rest/impl/RestTestImpl.java)
@RestControllerAdvice( basePackages = "es.um.atica.fundewebjsshowcasebackend" )
public class TestControllerAdvice extends ResponseEntityExceptionHandler {
/**
* Handler para la excepción raíz para validaciones javax.validation.ValidationException
*/
@ExceptionHandler( ValidationException.class )
public ResponseEntity<Object> handle( ValidationException ex ) {
final TestControllerAdviceError error = TestControllerAdviceError.builder().estado( HttpStatus.BAD_REQUEST )
.fecha( LocalDateTime.now() ).mensaje( ex.getMessage() ).build();
final List<String> errorList = new ArrayList<>();
if ( ex instanceof ConstraintViolationException ) {
final Set<ConstraintViolation<?>> constraintViolations = ( ( ConstraintViolationException ) ex )
.getConstraintViolations();
errorList.addAll( constraintViolations.stream()
.map( constraintViolation -> String.format( "%s value '%s' %s",
constraintViolation.getPropertyPath(), constraintViolation.getInvalidValue(),
constraintViolation.getMessage() ) )
.collect( Collectors.toList() ) );
} else {
errorList.add( ex.getMessage() );
}
error.setErroresValidacion( errorList );
return ResponseEntity.badRequest().body( error );
}
}
Fuentes:
TestControllerAdvice.java (https://gitlab.um.es/mncs/fundewebjsshowcase-api/-/blob/desarrollo/src/main/java/es/um/atica/fundewebjsshowcasebackend/handler/TestControllerAdvice.java)
POJO Error (https://gitlab.um.es/mncs/fundewebjsshowcase-api/-/blob/desarrollo/src/main/java/es/um/atica/fundewebjsshowcasebackend/error/TestControllerAdviceError.java).
Ejemplo de petición:
https://fundewebjsshowcasedesa.um.es/api/v1.0/public/handleError/5
{
"estado": "BAD_REQUEST",
"fecha": "13/10/2021 05:26:36",
"mensaje": "handleError.ex: must be less than or equal to 4",
"tipoRespuesta": "CUSTOM_ControllerAdvice",
"erroresValidacion": [
"handleError.ex value '5' must be less than or equal to 4"
]
}
La configuración y uso de Bean Validation queda como objetivo de la página de confluence: [EN CONSTRUCCIÓN]. Ante cualquier duda contacte con MNCS o revise las fuentes del proyecto de ejemplo fundewebjsshowcase-api.
Poner código de servicio y enlaces a gitlab.
Poner petición y respuesta ejemplo de postman.
Conclusión
Enumerar conclusiones, si se quiere hacer rápido usar ResponseStatusException, si se quiere cambiar la respuesta o el modelo y tenemos muchas excepciones usar ControllerAdvice + ResponseEntityExceptionHandler.
En un futuro cercano se integrará con el RFC Problem, se recomienda no elaborar muchos modelos de respuesta ya que posiblemente deban extender Problem.
Artículos Relacionados
- https://wiki.um.es/wikis/programador/doku.php?id=fdw2.0:fundeweb2.0:gt:rest:manejo_errores_rest
- https://www.baeldung.com/spring-response-status-exception
- https://www.baeldung.com/exception-handling-for-rest-with-spring
- https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/mvc/method/annotation/ResponseEntityExceptionHandler.html
- https://www.baeldung.com/problem-spring-web
- https://wiki.um.es/wikis/programador/doku.php?id=fdw2.0:fundeweb2.0:gt:rest:guia_validacion_servicio_rest
No hay ningún contenido con las etiquetas especificadas