Comment créer des pages d'erreur Spring Boot personnalisées avec Thymeleaf

Gestion des Erreurs dans les Applications Spring Boot

Toute application, même la plus sophistiquée, est susceptible de rencontrer des erreurs. Il est donc impératif de mettre en place des mécanismes robustes pour leur gestion.

Spring Boot, dans sa configuration par défaut, fournit une page d'erreur "Whitelabel" pour gérer ces situations. Cependant, il est souvent souhaitable de proposer une expérience utilisateur plus personnalisée. Cet article vous guide à travers la création de pages d'erreur sur mesure pour vos applications Spring Boot, en remplacement de la page Whitelabel standard.

La Page d'Erreur Whitelabel de Spring Boot

Quand une erreur se produit dans une application Spring Boot, celle-ci redirige vers l'URL "/error". Si aucune vue n'est associée à cette URL, c'est la page d'erreur Whitelabel qui s'affiche :

Cette page affiche la date et l'heure de l'erreur, ainsi que le fuseau horaire. Elle indique également le type d'erreur et son code associé. Par exemple, une erreur 404 (page non trouvée) est due au fait que l'exemple d'application n'a pas de correspondance pour l'URL "/products".

Les informations affichées proviennent d'attributs spécifiques liés à l'erreur. Spring Boot expose les attributs suivants à la vue d'erreur:

error : La cause de l'erreur.
horodatage : La date et l'heure de l'incident.
status : Le code d'état HTTP de l'erreur.
exception : Le nom de la classe de l'exception racine, si l'erreur est due à une exception.
message : Le message associé à l'exception, si applicable.
errors : Tous les résultats d'une exception BindingResult, en cas d'exception.
trace : La trace de la pile d'exception, si l'erreur résulte d'une exception.
path : Le chemin de l'URL où l'erreur s'est produite.

Personnalisation de la Page d'Erreur avec Thymeleaf

Pour personnaliser la gestion des erreurs, il est nécessaire de créer un modèle dédié, généralement nommé "error". L'extension de ce fichier dépend du moteur de modèles utilisé. Dans le cas d'un modèle Java Server Pages (JSP), on aurait un fichier nommé error.jsp.

Cependant, cet exemple utilise Thymeleaf. Le modèle sera donc nommé error.html et devra être placé dans le dossier des modèles, sous le répertoire des ressources.

Le Fichier error.html

 <!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
  <head>
    <title> Error</title>
    <link rel="stylesheet" href="https://wilku.top/how-to-create-custom-spring-boot-error-pages-with-thymeleaf/css/style.css"/>
  </head>
  <body style="background: url(/images/background1.jpg) no-repeat center center fixed;">
    <div class="container" >
      <h1>Une erreur est survenue...</h1>
      <img src="https://wilku.top/how-to-create-custom-spring-boot-error-pages-with-thymeleaf/images/error-icon.png" width="100px" height="100px" />
      <p>Un problème semble s'être produit avec la page que vous avez demandée (<span></span>).</p>
      <p>Le code d'état est       <p>Détails supplémentaires:       <a class="btn" href="https://wilku.top/home">Retour à l'accueil</a>
    </div>
  </body>
</html>

La page d'erreur personnalisée remplit plusieurs fonctions essentielles : elle indique clairement la survenue d'une erreur, présente la requête HTTP qui en est la cause, et affiche le code d'état correspondant. Pour les utilisateurs non familiers avec ces codes, elle fournit une explication grâce à l'attribut d'erreur.

Le dernier paragraphe présente le message d'exception, s'il existe, et un lien permet à l'utilisateur de retourner à la page d'accueil. Le fichier error.html utilise une feuille de style CSS et deux images pour structurer l'affichage. Voici à quoi elle ressemble :

Rendre Votre Page d'Erreur Conviviale

L'objectif primordial d'une page d'erreur est d'informer l'utilisateur de la nature du problème rencontré. Il est donc crucial de la rendre aussi claire et conviviale que possible.

Cela implique de sélectionner les attributs d'erreur les plus appropriés pour une communication efficace. Par exemple, privilégier l'attribut "path" à la "trace" qui est beaucoup plus complexe et contient des informations non nécessaires pour un utilisateur lambda.

De même, il est important de ne pas divulguer trop d'informations internes sur le fonctionnement de l'application, pour des raisons de sécurité.