Validation des données d'API avec Jakarta EE

1. Pourquoi valider les données en amont ?

Imaginez que quelqu'un essaie de créer un livre en envoyant un corps de requête JSON où le titre est manquant ou vide. Sans validation, cette donnée invalide pourrait se propager jusqu'à votre couche de service, voire jusqu'à la base de données, provoquant potentiellement une NullPointerException inattendue ou l'enregistrement de données corrompues.

La validation en amont agit comme un garde à l'entrée de votre API. Elle vérifie la qualité des données dès leur arrivée et rejette immédiatement ce qui est invalide.

Cette pratique est essentielle pour plusieurs raisons :

• Sécurité : Empêche les données malformées d'exploiter des failles potentielles.
• Intégrité des données : Garantit que seules des données conformes sont stockées.
• Robustesse : Évite des erreurs inattendues plus loin dans le code.
• Expérience développeur : Fournit un retour immédiat et clair au client de l'API sur ce qui ne va pas dans sa requête.

2. Intégrer Jakarta Bean Validation

Spring Boot facilite grandement l'utilisation de la validation. La spécification est Jakarta Bean Validation, et l'implémentation de référence, Hibernate Validator, est incluse par défaut lorsque vous utilisez la dépendance spring-boot-starter-web.

Le schéma suivant montre comment ces composants s'articulent :

3. Appliquer des règles de validation sur nos DTOs

La validation se fait en ajoutant des annotations directement sur les champs de nos objets de transfert de données (DTOs). Créons un DTO spécifique pour la création et la mise à jour de livres, que nous appellerons BookRequestDto.java dans votre package dto.

package com.votreprojet.dto;

public record BookRequestDto(
    String title,
    String author,
    Integer publicationYear
) {}

Maintenant, ajoutons des contraintes de validation. Pour cela, nous allons utiliser les annotations du package jakarta.validation.constraints.

La vidéo suivante montre en détail comment annoter une classe. Nous allons appliquer les mêmes principes à notre BookRequestDto.

En nous inspirant de la vidéo, modifions notre BookRequestDto.java :

package com.votreprojet.dto;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.PastOrPresent;
import jakarta.validation.constraints.Size;

public record BookRequestDto(
    @NotBlank(message = "Le titre ne peut pas être vide ou contenir uniquement des espaces")
    @Size(min = 2, max = 100, message = "Le titre doit contenir entre 2 et 100 caractères")
    String title,

    @NotBlank(message = "Le nom de l'auteur ne peut pas être vide")
    String author,

    @NotNull(message = "L'année de publication est obligatoire")
    @PastOrPresent(message = "L'année de publication ne peut pas être dans le futur")
    Integer publicationYear
) {}

Analyse des annotations utilisées :

• @NotBlank : S'assure que la chaîne n'est pas null et qu'elle contient au moins un caractère qui n'est pas un espace. C'est souvent plus strict et plus utile que @NotEmpty pour les champs texte.
• @Size : Valide que la taille du champ (ici, la longueur du String) est dans une plage donnée.
• @NotNull : Vérifie simplement que la valeur n'est pas null. Parfait pour les objets comme Integer.
• @PastOrPresent : Une annotation de date/heure qui vérifie que la valeur est dans le passé ou le présent.

4. Activer la validation dans le contrôleur

Avoir des annotations sur notre DTO ne suffit pas. Il faut indiquer à Spring de les vérifier au moment où une requête arrive. Pour cela, on utilise l'annotation @Valid sur le paramètre du contrôleur qui reçoit les données.

Modifions notre BookController.java pour les méthodes de création et de mise à jour. Assurez-vous d'utiliser le nouveau BookRequestDto et d'injecter @Valid.

// Dans BookController.java
// ...
import jakarta.validation.Valid;

@RestController
@RequestMapping("/api/books")
public class BookController {

    // ...

    @PostMapping
    public ResponseEntity<BookDto> createBook(@Valid @RequestBody BookRequestDto bookRequest) {
        BookDto createdBook = bookService.createBook(bookRequest);
        return new ResponseEntity<>(createdBook, HttpStatus.CREATED);
    }

    @PutMapping("/{id}")
    public ResponseEntity<BookDto> updateBook(@PathVariable Long id, @Valid @RequestBody BookRequestDto bookRequest) {
        BookDto updatedBook = bookService.updateBook(id, bookRequest);
        return new ResponseEntity<>(updatedBook, HttpStatus.OK);
    }
    
    // ...
}

Avec @Valid en place, si un client envoie une requête avec des données invalides (par exemple, un JSON sans le champ title), Spring lèvera automatiquement une MethodArgumentNotValidException.

5. Gérer les erreurs de validation proprement

À ce stade, une requête invalide provoquerait une erreur 400 Bad Request, mais avec un corps de réponse générique et peu lisible généré par Spring. Nous pouvons faire bien mieux en utilisant le GlobalExceptionHandler que nous avons créé dans la leçon précédente !

Nous allons l'enrichir pour qu'il intercepte MethodArgumentNotValidException et retourne une liste structurée des erreurs de validation.

Appliquons cette logique à notre GlobalExceptionHandler.java.

// Dans GlobalExceptionHandler.java
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.validation.FieldError;
import java.util.HashMap;
import java.util.Map;

// ...

@ControllerAdvice
public class GlobalExceptionHandler {

    // ... (gardez les gestionnaires précédents pour ResourceNotFoundException et Exception)

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleValidationExceptions(MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getAllErrors().forEach((error) -> {
            String fieldName = ((FieldError) error).getField();
            String errorMessage = error.getDefaultMessage();
            errors.put(fieldName, errorMessage);
        });
        return new ResponseEntity<>(errors, HttpStatus.BAD_REQUEST);
    }
}

Analyse du code :

1. On crée un ExceptionHandler qui cible MethodArgumentNotValidException.
2. On initialise une Map<String, String> pour stocker les erreurs (nom du champ -> message d'erreur).
3. ex.getBindingResult().getAllErrors() nous donne la liste de toutes les erreurs de validation.
4. On parcourt cette liste. Pour chaque erreur, on la caste en FieldError pour obtenir le nom du champ (getField()) et on récupère le message d'erreur (getDefaultMessage()). Ce message est celui que nous avons défini dans l'annotation sur le DTO !
5. On retourne la Map d'erreurs avec un statut 400 Bad Request.

Maintenant, si vous testez avec Postman en envoyant une requête de création avec un corps vide {} à /api/books, vous obtiendrez une réponse 400 Bad Request claire et utile :

{
    "author": "Le nom de l'auteur ne peut pas être vide",
    "publicationYear": "L'année de publication est obligatoire",
    "title": "Le titre ne peut pas être vide ou contenir uniquement des espaces"
}

Le client de l'API sait exactement ce qu'il doit corriger.

Conclusion

Félicitations ! Vous avez ajouté une couche de validation robuste à votre API, la rendant plus sûre et plus facile à utiliser.

Points clés à retenir :

• Validation Déclarative : Les annotations de Jakarta Bean Validation (@NotBlank, @Size, etc.) permettent de définir des règles directement sur les DTOs, séparant la validation de la logique métier.
• Déclenchement via @Valid : L'annotation @Valid sur un @RequestBody dans un contrôleur active le processus de validation.
• Gestion d'Erreurs Spécifique : L'exception MethodArgumentNotValidException est levée en cas d'échec de la validation.
• Retour Informatif : En interceptant cette exception dans un @ControllerAdvice, vous pouvez construire et renvoyer une réponse 400 Bad Request structurée qui guide l'utilisateur pour corriger sa requête.

Notre API est maintenant capable de gérer les cas où les ressources n'existent pas (404) et où les données d'entrée sont invalides (400). La prochaine étape logique est de s'assurer que tout ce comportement fonctionne comme prévu.

Dans la prochaine leçon, nous apprendrons à tester nos endpoints d'API REST à l'aide d'un client HTTP comme Postman. Nous verrons comment créer et organiser des requêtes pour vérifier les cas de succès, les erreurs 404, et nos nouvelles erreurs de validation 400.