Formations — 1 037 leçons en français

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, detail et instance, plus des extensions libres. Elle remplace la RFC 7807, dont elle reprend le contenu. Le type de média associé est application/problem+json.

ProblemDetail

Classe de Spring Framework 6 (org.springframework.http.ProblemDetail) qui matérialise ce format. On la construit avec forStatus(...) ou forStatusAndDetail(...), et on y ajoute des champs libres avec setProperty(nom, valeur).

@RestControllerAdvice

Classe annotée qui regroupe des @ExceptionHandler appliqué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 les try/catch dans les contrôleurs.

ResponseEntityExceptionHandler

Classe de base fournie par Spring MVC que l'on peut étendre dans son @RestControllerAdvice pour hériter du traitement des exceptions internes de Spring (corps JSON illisible, méthode non supportée, validation…) sous forme de ProblemDetail.

spring.mvc.problemdetails.enabled

Propriété qui fait produire par Spring Boot des réponses ProblemDetail pour les exceptions que Spring MVC gère lui-même. À noter : elle est sans effet si vous étendez ResponseEntityExceptionHandler, qui prend alors le relais.

Code d'erreur métier

Identifiant stable, destiné au code et non à l'humain (STOCK_INSUFFISANT), ajouté en extension du ProblemDetail. C'est sur lui que le front branche un comportement : le title et le detail peuvent ê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.

Lire l'explication détaillée et faire le quiz →

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.