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.
En el siguiente apartado se muestran ejemplos de cómo construir respuestas y usar estos códigos.
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 significa el 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.
ResponseStatusException
Permite lanzar una excepción pasando como parámetro un código de respuesta.
Devuelve el modelo de respuesta estándar.
Ventajas: rápido, código http distinto con cada
Desventajas: Modelo de respuesta fijo
Poner código de servicio y enlaces a gitlab.
Poner petición y respuesta ejemplo de postman.
(Hablar de ResponseStatus y mencionar el otro ejemplo)
DefaultErrorAttributes
Definición del modelo de respuesta estándar.
Se puede modificar y declarar para configurar un modelo de respuesta común para toda la aplicación.Poner código de servicio y enlaces a gitlab.
Poner petición y respuesta ejemplo de postman.ExceptionHandler
Manejar excepciones de forma local, permite modificar valores de la respuesta http así como el modelo.
Desventajas: solo funciona de forma local.
Poner código de servicio y enlaces a gitlab.
Poner petición y respuesta ejemplo de postman.
ControllerAdvice
Permite centralizar el manejo de excepciones para que se capturen de forma global.
Poner código de servicio y enlaces a gitlab.
Poner petición y respuesta ejemplo de postman.
ControllerAdvice + ResponseEntityExceptionHandler
Permite extender y sobreescribir el manejo de las excepciones internas que realiza Spring Boot de forma automática.
Poner listado de excepciones.
Poner código de servicio y enlaces a gitlab.
Poner petición y respuesta ejemplo de postman.Bean Validation
Configuración y uso de Bean Validation.
Handlers a sobreescribir para modificar respuesta HTTP o modelo.
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://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