MapStruct Java : guide complet avec exemples pratiques

Qu'est-ce que MapStruct et pourquoi l'utiliser ?

MapStruct est un générateur de code pour Java qui crée automatiquement des implémentations de mappers (transformateurs) entre des objets de différents types. Dans le développement Java moderne, on doit souvent transformer un objet en un autre : Entity en DTO, DTO en VO, une réponse API en un autre modèle, etc. Écrire ce code manuellement est une tâche fastidieuse, chronophage et source d'erreurs. MapStruct résout ce problème en générant tout le code passe-partout (boilerplate) à la compilation.

Les principaux avantages de MapStruct :

• Performance : Génération de code à la compilation (compile-time). Pas de réflexion, pas de perte de performance à l'exécution. MapStruct est aussi rapide qu'un mapping écrit manuellement.
• Sécurité des types : Toutes les erreurs (incompatibilité de types, champs manquants) sont détectées à la compilation, et non à l'exécution.
• Simplicité : Configuration minimale. Il suffit de définir une interface ou une classe abstraite avec des méthodes de mapping, et MapStruct génère l'implémentation automatiquement.
• Flexibilité : Prise en charge des mappings complexes, des conversions de types, des expressions, des appels de méthodes et de l'intégration avec d'autres bibliothèques (Lombok, Spring, etc.).
• Code propre : Le code de mapping est séparé de la logique métier, ce qui le rend plus lisible et maintenable.

MapStruct est particulièrement utile dans les architectures multicouches (Controller-Service-Repository), où la transformation d'objets entre les couches est fréquente.

Installation de MapStruct

MapStruct ne s'installe pas via pip ou npm, car c'est une bibliothèque Java. Pour ajouter MapStruct à votre projet, utilisez le système de build Maven ou Gradle.

Installation avec Maven

Ajoutez les dépendances suivantes dans votre fichier pom.xml :

<dependencies>
    <!-- Bibliothèque principale MapStruct -->
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>1.5.5.Final</version>
    </dependency>

    <!-- Processeur d'annotations (pour la génération de code) -->
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct-processor</artifactId>
        <version>1.5.5.Final</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Installation avec Gradle

Pour Gradle, ajoutez dans le fichier build.gradle :

dependencies {
    implementation 'org.mapstruct:mapstruct:1.5.5.Final'
    annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'
}

Important : Assurez-vous que la version de mapstruct-processor correspond à celle de mapstruct. Après avoir ajouté les dépendances, lancez la compilation du projet (par exemple, mvn clean compile) pour que MapStruct génère les implémentations des mappers.

Démarrage rapide avec un exemple de code

Créons un mapper simple qui transforme un objet Car (Entity) en un objet CarDto (DTO).

Étape 1 : Définissez les classes source et cible

// Car.java
public class Car {
    private String make;
    private int numberOfSeats;
    private CarType type;

    // constructeurs, getters, setters
    public Car() {}

    public Car(String make, int numberOfSeats, CarType type) {
        this.make = make;
        this.numberOfSeats = numberOfSeats;
        this.type = type;
    }

    public String getMake() { return make; }
    public void setMake(String make) { this.make = make; }
    public int getNumberOfSeats() { return numberOfSeats; }
    public void setNumberOfSeats(int numberOfSeats) { this.numberOfSeats = numberOfSeats; }
    public CarTy