Gestion des erreurs spécifiques à Spring Boot (page d'erreur Whitelabel)

Le filet de sécurité par défaut : la page d'erreur Whitelabel

Même avec une gestion globale des exceptions bien configurée via @ControllerAdvice, certaines erreurs peuvent encore survenir en dehors du périmètre de vos contrôleurs habituels. Par exemple, une requête vers une URL inexistante (erreur 404 Not Found) ou une erreur se produisant très tôt dans le traitement de la requête par le conteneur de servlets ou le framework Spring lui-même, avant même qu'un contrôleur ou votre @ControllerAdvice n'ait pu intervenir.

Pour éviter de laisser l'utilisateur face à une page d'erreur brute du serveur (souvent peu esthétique et pouvant révéler des informations sensibles), Spring Boot fournit un mécanisme de gestion des erreurs par défaut, appelé la "Whitelabel Error Page". C'est une page HTML simple, sans marque (d'où "Whitelabel"), qui s'affiche comme un filet de sécurité pour fournir des informations de base sur l'erreur survenue.

Cette page est particulièrement utile pendant le développement car elle donne rapidement un aperçu de ce qui s'est mal passé. Cependant, en production, il est généralement préférable de la remplacer par une page d'erreur personnalisée et plus conviviale pour l'utilisateur final.

Quand la page Whitelabel entre-t-elle en jeu ?

La page d'erreur Whitelabel est affichée par Spring Boot dans les situations suivantes (liste non exhaustive) :

• Erreur 404 Not Found : Lorsqu'un client demande une URL qui ne correspond à aucun mapping de contrôleur ni à aucune ressource statique connue.
• Erreurs non capturées par @ExceptionHandler : Si une exception est levée mais qu'aucun @ExceptionHandler (ni dans le contrôleur, ni dans un @ControllerAdvice) n'est défini pour ce type d'exception spécifique ou ses super-classes.
• Erreurs du conteneur ou du framework : Erreurs survenant lors du traitement de la requête par le conteneur de servlets (Tomcat, Jetty, etc.) ou par Spring avant/après l'invocation du contrôleur (par exemple, un problème de désérialisation non géré, un type de média non supporté si aucun handler spécifique n'est prévu).
• Accès direct à /error : Si vous accédez directement à l'URL /error sans qu'une erreur préalable ne se soit produite (bien que le comportement puisse varier).

Il est important de noter que si vous avez un @ExceptionHandler(Exception.class) dans votre @ControllerAdvice, celui-ci interceptera la plupart des exceptions survenant *pendant* l'exécution de vos méthodes de contrôleur, et la page Whitelabel ne sera alors pas sollicitée pour ces cas spécifiques (sauf si votre handler lui-même échoue).

Anatomie de la page Whitelabel

La page HTML Whitelabel par défaut affiche généralement les informations suivantes :

• Timestamp : Date et heure de l'erreur.
• Status : Le code de statut HTTP (ex: 404, 500, 400).
• Error : La description textuelle standard du code de statut (ex: Not Found, Internal Server Error, Bad Request).
• Message : Un message d'erreur plus spécifique, s'il est disponible (peut être le message de l'exception ou une description fournie par le framework). Pour les erreurs 404, c'est souvent "No message available" ou lié au chemin non trouvé.
• Path : L'URL de la requête qui a causé l'erreur.
• Trace (optionnel) : Une trace de la pile (stack trace) de l'exception peut également être affichée. C'est très utile en développement pour diagnostiquer les erreurs 500, mais doit absolument être désactivé en production pour des raisons de sécurité.

L'inclusion de la trace de pile est contrôlée par la propriété server.error.include-stacktrace dans votre fichier application.properties ou application.yml. Les valeurs possibles sont :

• NEVER (Défaut) : Jamais incluse.
• ALWAYS : Toujours incluse (dangereux en production !).
• ON_PARAM : Incluse seulement si la requête contient un paramètre nommé trace avec la valeur true (ex: /error?trace=true). C'est un bon compromis pour le développement.

# application.properties: Pour afficher la trace en développement si trace=true est dans l'URL
server.error.include-stacktrace=on_param

Le mécanisme sous-jacent : `BasicErrorController`

Comment Spring Boot affiche-t-il cette page ? Grâce à l'auto-configuration, Spring Boot enregistre un contrôleur spécial nommé BasicErrorController. Ce contrôleur est mappé sur le chemin /error.

Lorsque le conteneur de servlets ou le framework rencontre une erreur qu'il ne sait pas gérer autrement (ou une erreur 404), il effectue généralement un renvoi interne (forward) vers le chemin /error. Le BasicErrorController prend alors la main.

Ce contrôleur est capable de produire deux types de réponses en fonction de l'en-tête Accept de la requête originale :

• Si le client demande du HTML (Accept: text/html), le BasicErrorController tente de rendre une vue nommée "error". S'il ne trouve pas de template personnalisé nommé "error", il utilise la vue Whitelabel par défaut.
• Si le client demande du JSON (Accept: application/json) ou un autre type de média, le BasicErrorController génère une réponse JSON contenant les attributs d'erreur (timestamp, status, error, message, path, trace [si configuré]). C'est très utile pour les clients d'API REST qui préfèrent recevoir les erreurs dans un format structuré.

Personnaliser ou remplacer la page Whitelabel

Comme mentionné, la page Whitelabel n'est généralement pas adaptée à un environnement de production. Spring Boot offre plusieurs moyens de la personnaliser ou de la remplacer :

1. Pages d'erreur statiques par code de statut : Le moyen le plus simple est de fournir vos propres fichiers HTML statiques dans un répertoire error/ situé sous l'un des répertoires de contenu statique (ex: src/main/resources/static/error/ ou src/main/resources/public/error/). Nommez les fichiers d'après le code de statut HTTP (ex: 404.html, 500.html). Si une erreur avec ce statut se produit, Spring Boot servira automatiquement le fichier HTML correspondant.

src/main/resources/
└── static/
    └── error/
        ├── 404.html  (Page pour les erreurs 404)
        ├── 500.html  (Page pour les erreurs 5xx)
        └── general.html (Optionnel, pour autres erreurs)

2. Page d'erreur dynamique avec un template : Si vous utilisez un moteur de templates comme Thymeleaf, vous pouvez créer un template nommé error.html dans votre répertoire de templates (ex: src/main/resources/templates/error.html). Le BasicErrorController l'utilisera à la place de la vue Whitelabel. Ce template peut accéder aux attributs d'erreur (timestamp, status, error, message, path, trace) via le modèle pour afficher une page d'erreur plus informative et mieux intégrée au style de votre application. Vous pouvez aussi créer des templates spécifiques par code d'erreur (ex: templates/error/404.html).
3. Implémenter votre propre `ErrorController` : Pour un contrôle total, vous pouvez créer votre propre bean implémentant l'interface ErrorController et le mapper sur /error. Cela remplace complètement le BasicErrorController et vous donne la responsabilité de générer la réponse d'erreur (HTML, JSON, etc.).
4. Désactiver complètement la Whitelabel : Si vous préférez laisser le conteneur de servlets gérer l'erreur (ce qui n'est généralement pas recommandé), vous pouvez désactiver la page Whitelabel via une propriété :

# application.properties
server.error.whitelabel.enabled=false

Conclusion : Un comportement par défaut utile mais à adapter

La page d'erreur Whitelabel de Spring Boot est un mécanisme par défaut pratique qui fournit un retour immédiat lors du développement en cas d'erreurs non gérées spécifiquement. Elle est rendue par le BasicErrorController, qui gère le chemin /error et peut produire du HTML ou du JSON.

Cependant, pour une application en production, il est essentiel de fournir une expérience utilisateur plus soignée et sécurisée. Cela implique généralement de combiner une gestion globale des exceptions applicatives avec @ControllerAdvice et @ExceptionHandler (qui retournent souvent des réponses JSON structurées pour les API) avec la personnalisation des pages d'erreur pour les cas non couverts (comme les 404) en fournissant vos propres vues statiques ou dynamiques mappées sur les codes de statut ou sur le chemin /error.