Formations — 1 037 leçons en français

Accueil › Spring Boot › @ExceptionHandler et @RestControllerAdvice

@ExceptionHandler et @RestControllerAdvice

Créer une API RESTdebutant

Sans gestion particulière, une exception non interceptée aboutit sur l'endpoint /error de Spring Boot, avec un code 500 et une réponse JSON générique. Pour des réponses précises et cohérentes, on définit des exceptions métier et on les intercepte avec @ExceptionHandler :

public class ProduitIntrouvableException extends RuntimeException {
    public ProduitIntrouvableException(Long id) {
        super("Produit introuvable : " + id);
    }
}

@RestControllerAdvice
public class GestionnaireErreurs {

    @ExceptionHandler(ProduitIntrouvableException.class)
    public ResponseEntity<String> gererProduitIntrouvable(ProduitIntrouvableException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

@RestControllerAdvice centralise ces gestionnaires pour tous les contrôleurs de l'application, au lieu de répéter @ExceptionHandler dans chacun. On peut aussi en mettre un directement dans un contrôleur : il ne s'applique alors qu'à ce contrôleur.

Règle essentielle : ne jamais renvoyer au client le message brut d'une exception technique ni sa pile d'appel — cela peut exposer des détails internes de l'application.

Les termes à connaître

Exception métier

Une exception propre au domaine de l'application, par exemple ProduitIntrouvableException, levée par le code métier (service, repository) plutôt que de renvoyer null ou un Optional vide partout.

@ExceptionHandler

Annotation posée sur une méthode qui intercepte un type d'exception précis et construit la réponse HTTP correspondante. Peut être locale à un contrôleur, ou globale dans une classe @RestControllerAdvice.

@RestControllerAdvice

Raccourci pour @ControllerAdvice + @ResponseBody : une classe qui centralise des @ExceptionHandler pour tous les contrôleurs de l'application, au lieu de les dupliquer dans chacun.

ResponseStatusException

Exception prête à l'emploi de Spring (org.springframework.web.server.ResponseStatusException) qui porte directement un code HTTP et un message, pratique pour une erreur ponctuelle sans créer de classe dédiée.

ProblemDetail

Classe Spring 6 (org.springframework.http.ProblemDetail) qui représente une erreur au format RFC 9457 (Problem Details for HTTP APIs) : type, title, status, detail, instance, et des champs additionnels propres à l'application.

spring.mvc.problemdetails.enabled

Propriété qui active la production de réponses ProblemDetail (au format application/problem+json) pour les exceptions que Spring MVC gère lui-même en interne (ex. HttpMessageNotReadableException, MethodArgumentNotValidException).

/error

Endpoint géré par BasicErrorController, appelé automatiquement quand une exception n'est interceptée par aucun @ExceptionHandler. Produit une réponse JSON par défaut avec timestamp, status, error, path (le message et la pile d'appel ne sont inclus que si on l'active explicitement).

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.