Validation des DTOs avec Bean Validation

1. Le principe de la Bean Validation

En tant que développeur expérimenté, vous avez sans doute écrit d'innombrables fois du code de validation manuel, que ce soit en JavaScript ou en PHP.

if (empty($_POST['email']) || !filter_var($_POST['email'], FILTER_VALIDATE_EMAIL)) {
    // return error
}

Ce type de code, bien que fonctionnel, est répétitif et encombre la logique métier. La spécification Bean Validation (JSR 380) propose une approche beaucoup plus élégante et centralisée. L'idée est de définir les règles de validation directement sur vos objets (nos DTOs) à l'aide d'annotations. Spring Boot s'occupe ensuite d'appliquer ces règles automatiquement.

Spring Boot intègre par défaut Hibernate Validator, l'implémentation de référence de cette spécification. Pour être sûr que tout est en place, nous nous assurons que la dépendance spring-boot-starter-validation est présente dans notre pom.xml.

2. Définir des contraintes sur un DTO

La partie la plus visible de la Bean Validation consiste à annoter les champs de vos classes DTO. Ces annotations sont déclaratives : elles décrivent ce que les données doivent être, pas comment les valider.

La vidéo suivante vous guidera pas à pas dans l'ajout de ces contraintes sur un DTO d'exemple.

Pour récapituler, voici un exemple de DTO ProductDTO avec des annotations de validation typiques :

import jakarta.validation.constraints.*;

public class ProductDTO {

    @NotBlank(message = "Le nom du produit ne peut pas être vide.")
    @Size(min = 3, max = 100, message = "Le nom doit contenir entre 3 et 100 caractères.")
    private String name;

    @NotNull(message = "Le prix ne peut pas être nul.")
    @Positive(message = "Le prix doit être un nombre positif.")
    private Double price;

    @Min(value = 0, message = "Le stock ne peut pas être négatif.")
    private int stock;

    // Getters and setters
}

Vous pouvez retrouver une liste de ces annotations et leur usage dans les ressources LINK (section "Validation d'objets avec des annotations") et LINK (section "Créer un nouveau client").

3. Activer la validation dans le contrôleur

Avoir des DTOs annotés ne suffit pas. Il faut indiquer à Spring Boot de déclencher le processus de validation à un moment précis. Pour une API REST, ce moment est la réception d'une requête HTTP, juste avant que le corps de votre méthode de contrôleur ne soit exécuté.

Ceci se fait avec une seule annotation : @Valid.

Voici à quoi ressemble une méthode de contrôleur avec la validation activée :

@RestController
@RequestMapping("/api/products")
public class ProductController {

    @PostMapping
    public ResponseEntity<Product> createProduct(@Valid @RequestBody ProductDTO productDTO) {
        // Si le code atteint ce point, c'est que productDTO est valide.
        // Logique pour créer le produit...
        return new ResponseEntity<>(createdProduct, HttpStatus.CREATED);
    }
}

Si les données envoyées dans le corps de la requête ne respectent pas les contraintes définies dans ProductDTO, Spring lèvera une exception MethodArgumentNotValidException et n'exécutera pas le code à l'intérieur de la méthode createProduct. C'est une barrière de protection cruciale qui empêche les données invalides de contaminer votre logique métier.

4. Gérer et retourner des erreurs de validation claires

Par défaut, lorsqu'une MethodArgumentNotValidException est levée, Spring Boot retourne une réponse HTTP 400 Bad Request avec un corps JSON complexe et peu lisible. Pour une API professionnelle, c'est inacceptable. Votre client frontend (une application React, par exemple) a besoin de savoir précisément quel champ est en erreur et pourquoi.

La solution consiste à intercepter cette exception de manière centralisée et à formater une réponse d'erreur claire. C'est un cas d'usage parfait pour un @RestControllerAdvice.

Le code d'un tel gestionnaire ressemble à ceci :

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import java.util.HashMap;
import java.util.Map;

@RestControllerAdvice
public class GlobalExceptionHandler {

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

Avec ce gestionnaire en place, si un client envoie un ProductDTO avec un nom vide et un prix négatif, la réponse de l'API sera :

{
    "name": "Le nom du produit ne peut pas être vide.",
    "price": "Le prix doit être un nombre positif."
}

Cette approche est extrêmement précieuse. Votre expérience en développement frontend vous a sûrement montré à quel point il est plus simple d'afficher des erreurs dans un formulaire lorsque l'API retourne une structure de données aussi prévisible.

Conclusion

Félicitations ! Vous avez ajouté une couche de protection indispensable à votre API. En maîtrisant la validation des données, vous garantissez l'intégrité des informations qui entrent dans votre système, ce qui réduit les bugs et améliore la sécurité.

Points clés à retenir :

• Bean Validation est une spécification Java standard pour la validation déclarative des données via des annotations (@NotNull, @Size, etc.) sur les DTOs.
• La validation est activée dans un contrôleur en ajoutant l'annotation @Valid à un paramètre @RequestBody.
• En cas d'échec de la validation, Spring lève une MethodArgumentNotValidException, empêchant l'exécution de la logique métier avec des données invalides.
• On utilise un @RestControllerAdvice pour intercepter cette exception et retourner une réponse 400 Bad Request avec une structure d'erreurs claire et exploitable pour le client.

Dans la prochaine leçon, nous allons généraliser le concept que nous venons d'effleurer. Nous allons voir comment utiliser @ControllerAdvice pour centraliser la gestion de toutes les erreurs de l'application, y compris les erreurs métier (ex: "Produit non trouvé") et les erreurs techniques, afin de fournir des réponses HTTP cohérentes et professionnelles en toutes circonstances.