Accueil › Fullstack Angular + Spring Boot › Un format d'erreur unique avec ProblemDetail
Un format d'erreur unique avec ProblemDetail
Les erreurs de bout en boutdebutant
Sans convention, chaque endpoint invente son format d'erreur : {"message":"..."} ici, {"error":"..."} là, du HTML de Tomcat ailleurs. Le front finit avec un empilement de if illisible.
Un seul @RestControllerAdvice suffit à normaliser toute l'API :
@RestControllerAdvice
public class GestionnaireErreurs extends ResponseEntityExceptionHandler {
@ExceptionHandler(RessourceIntrouvableException.class)
ProblemDetail introuvable(RessourceIntrouvableException ex) {
ProblemDetail p = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
p.setTitle("Ressource introuvable");
p.setProperty("code", "RESSOURCE_INTROUVABLE");
return p;
}
@ExceptionHandler(Exception.class)
ProblemDetail inattendue(Exception ex) {
log.error("Erreur inattendue", ex); // le détail reste dans les journaux
ProblemDetail p = ProblemDetail.forStatus(HttpStatus.INTERNAL_SERVER_ERROR);
p.setTitle("Erreur interne");
p.setDetail("Une erreur inattendue est survenue.");
p.setProperty("code", "ERREUR_INTERNE");
return p;
}
}
Le front obtient toujours la même forme :
export interface ProblemDetail {
type?: string;
title?: string;
status: number;
detail?: string;
instance?: string;
code?: string; // notre extension
erreursChamps?: Record<string, string>; // voir la leçon suivante
}
Un seul type, un seul traitement, et des messages d'erreur cohérents dans toute l'application.
Les termes à connaître
- RFC 9457 (Problem Details)
Norme qui décrit un format JSON standard pour les erreurs d'API, avec les champs
type,title,status,detailetinstance, plus des extensions libres. Elle remplace la RFC 7807, dont elle reprend le contenu. Le type de média associé estapplication/problem+json.- ProblemDetail
Classe de Spring Framework 6 (
org.springframework.http.ProblemDetail) qui matérialise ce format. On la construit avecforStatus(...)ouforStatusAndDetail(...), et on y ajoute des champs libres avecsetProperty(nom, valeur).- @RestControllerAdvice
Classe annotée qui regroupe des
@ExceptionHandlerappliqués à tous les contrôleurs de l'application. C'est l'endroit unique où l'on traduit les exceptions métier en réponses HTTP, au lieu de multiplier lestry/catchdans les contrôleurs.- ResponseEntityExceptionHandler
Classe de base fournie par Spring MVC que l'on peut étendre dans son
@RestControllerAdvicepour hériter du traitement des exceptions internes de Spring (corps JSON illisible, méthode non supportée, validation…) sous forme deProblemDetail.- spring.mvc.problemdetails.enabled
Propriété qui fait produire par Spring Boot des réponses
ProblemDetailpour les exceptions que Spring MVC gère lui-même. À noter : elle est sans effet si vous étendezResponseEntityExceptionHandler, qui prend alors le relais.- Code d'erreur métier
Identifiant stable, destiné au code et non à l'humain (
STOCK_INSUFFISANT), ajouté en extension duProblemDetail. C'est sur lui que le front branche un comportement : letitleet ledetailpeuvent être réécrits ou traduits sans rien casser.- Identifiant de corrélation
Identifiant unique attaché à une requête (souvent l'identifiant de trace), renvoyé dans l'erreur et journalisé côté serveur. Il permet de retrouver la pile d'appels exacte à partir d'une capture d'écran envoyée par un utilisateur.
Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.