ModelMapper pour Java : Guide complet du mapping automatique d'objets

1. Qu'est-ce que ModelMapper et pourquoi l'utiliser ?

ModelMapper est une bibliothèque Java puissante conçue pour transformer automatiquement (mapper) des objets d'un type vers un autre. Dans le développement moderne, notamment avec une architecture en couches (Controller → Service → Repository), les développeurs doivent constamment copier des données entre DTO (Data Transfer Objects), entités de base de données, VO (Value Objects) et autres POJO. Écrire ce code manuellement est une tâche fastidieuse, source d'erreurs, qui alourdit le code et réduit sa lisibilité.

L'objectif principal de ModelMapper est de libérer le développeur de l'écriture de code répétitif du type source.getField() → target.setField(). La bibliothèque analyse la structure des classes (champs, getters/setters) et les fait correspondre automatiquement en utilisant des conventions de nommage (convention over configuration). Elle prend en charge les objets imbriqués, les collections, l'héritage et les transformations complexes, ce qui en fait un outil indispensable pour les applications Java d'entreprise.

ModelMapper est particulièrement utile dans les scénarios suivants :

• Couches applicatives : Transformation d'entités en DTO et vice-versa pour la transmission de données via une API REST.
• Microservices : Mapping entre objets de différents services.
• Refactoring : Lorsque la structure des classes change, il suffit de modifier le mapping à un seul endroit.
• Tests : Création rapide de données de test à partir d'objets existants.

2. Installation

ModelMapper est distribué via Maven Central. Pour l'installer, ajoutez la dépendance dans votre fichier pom.xml (pour Maven) ou build.gradle (pour Gradle).

Maven (pom.xml) :

<dependency>
    <groupId>org.modelmapper</groupId>
    <artifactId>modelmapper</artifactId>
    <version>3.2.0</version>
</dependency>

Gradle (build.gradle) :

implementation 'org.modelmapper:modelmapper:3.2.0'

Remarque : La version 3.2.0 est celle en vigueur au moment de la rédaction. Il est recommandé de vérifier la dernière version sur MVNRepository.

3. Démarrage rapide — exemple minimal fonctionnel

Prenons un exemple simple : nous avons une classe UserEntity (entité de base de données) et une classe UserDTO (objet de transfert de données).

// Classe source (Entity)
public class UserEntity {
    private Long id;
    private String firstName;
    private String lastName;
    private String email;

    // Constructeurs, getters et setters
    public UserEntity() {}
    public UserEntity(Long id, String firstName, String lastName, String email) {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
        this.email = email;
    }

    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getFirstName() { return firstName; }
    public void setFirstName(String firstName) { this.firstName = firstName; }
    public String getLastName() { return lastName; }
    public void setLastName(String lastName) { this.lastName = lastName; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
}

// Classe cible (DTO)
public class UserDTO {
    private Long id;
    private String fullName; // Remarque : le champ a un nom différent
    private String emailAddress;

    // Constructeurs, getters et setters
    public UserDTO() {}
    public Long getId() { return id; }
    public void