ModelMapper para Java: Guía completa de mapeo automático de objetos

1. ¿Qué es ModelMapper y por qué usarlo?

ModelMapper es una potente biblioteca para Java diseñada para transformar (mapear) objetos de un tipo a otro de forma automática. En el desarrollo moderno, especialmente con arquitecturas multicapa (Controller → Service → Repository), los desarrolladores necesitan copiar datos constantemente entre DTO (Data Transfer Objects), Entity (entidades de base de datos), VO (Value Objects) y otros POJO. Escribir este código manualmente es tedioso, propenso a errores y genera código inflado y difícil de leer.

El objetivo principal de ModelMapper es eliminar la necesidad de escribir código repetitivo como source.getField() → target.setField(). La biblioteca analiza la estructura de las clases (campos, getters/setters) y las empareja automáticamente usando convenciones de nomenclatura (convention over configuration). Soporta objetos anidados, colecciones, herencia y transformaciones complejas, convirtiéndose en una herramienta indispensable en aplicaciones empresariales Java.

ModelMapper es especialmente útil en estos escenarios:

• Capas de la aplicación: Convertir Entity a DTO y viceversa para transferir datos a través de APIs REST.
• Microservicios: Mapear objetos entre diferentes servicios.
• Refactorización: Cuando cambia la estructura de clases, solo necesitas modificar el mapeo en un lugar.
• Pruebas: Crear datos de prueba rápidamente a partir de objetos existentes.

2. Instalación

ModelMapper se distribuye a través de Maven Central. Para instalarlo, agrega la dependencia en tu archivo pom.xml (para Maven) o build.gradle (para 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'

Nota: La versión 3.2.0 es la actual al momento de escribir esta guía. Te recomendamos verificar la última versión en MVNRepository.

3. Inicio rápido — ejemplo mínimo funcional

Veamos un ejemplo sencillo: tenemos la clase UserEntity (entidad de base de datos) y UserDTO (objeto para transferencia de datos).

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

    // Constructores, getters y 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; }
}

// Clase destino (DTO)
public class UserDTO {
    private Long id;
    private String fullName; // Nota: el campo tiene otro nombre
    private String emailAddress;

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