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 renvoyernullou unOptionalvide 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@ExceptionHandlerpour 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 formatapplication/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 avectimestamp,status,error,path(le message et la pile d'appel ne sont inclus que si on l'active explicitement).
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.