Artículo

ModelMapper en Java: convertir entidades a DTOs paso a paso

Cómo usar ModelMapper en Java y Spring Boot para convertir entidades en DTOs: mapeo automático, aplanado, mapeos personalizados, validación y listas.

En resumen: ModelMapper copia datos entre objetos por convención de nombres: mapper.map(cliente, ClienteDto.class) rellena los campos que coinciden y aplana propiedades anidadas (direccion.ciudad → direccionCiudad). Para lo que no coincide, se configura un TypeMap. Usa MatchingStrategies.STRICT y validate() para que un campo sin mapear sea un error y no un null silencioso. Probado con ModelMapper 3.2.4 y Java 21.

Vídeo explicativo

Para qué sirve

En una API no conviene devolver las entidades tal cual: expondrías campos internos (como la contraseña), acoplarías el JSON a la base de datos y tendrías problemas con las relaciones perezosas. La solución es el patrón DTO, y ModelMapper evita escribir a mano el código que copia campo a campo.

Dependencia

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

Las clases

ModelMapper trabaja con getters y setters, así que el destino necesita un constructor vacío y setters:

public class Direccion {
    private String ciudad;
    private String calle;
    // getters y setters
}

public class Cliente {
    private Long id;
    private String nombre;
    private String password;
    private Direccion direccion;
    // getters y setters
}

public class ClienteDto {
    private Long id;
    private String nombre;
    private String direccionCiudad;    // aplanado: direccion.ciudad
    private String nombreCompleto;     // sin equivalente: se configura a mano
    // getters y setters
}

Mapeo automático

ModelMapper mapper = new ModelMapper();
ClienteDto dto = mapper.map(cliente(1, "Ana", "Valencia"), ClienteDto.class);
id=1, nombre=Ana, direccionCiudad=Valencia, nombreCompleto=null

id y nombre coinciden por nombre; direccionCiudad se rellenó solo, al reconocer direccion + ciudad. password no existe en el DTO, así que no se copia. Pero nombreCompleto quedó en null sin ningún aviso: es el riesgo principal de mapear por convención.

Mapeo personalizado y validación

ModelMapper mapper = new ModelMapper();
mapper.getConfiguration().setMatchingStrategy(MatchingStrategies.STRICT);
mapper.typeMap(Cliente.class, ClienteDto.class).addMappings(m -> {
    m.map(src -> src.getDireccion().getCiudad(), ClienteDto::setDireccionCiudad);
    m.map(Cliente::getNombre, ClienteDto::setNombreCompleto);
});
mapper.validate();    // falla si algún campo del destino queda sin origen

List<ClienteDto> dtos = mapper.map(
        List.of(cliente(1, "Ana", "Valencia"), cliente(2, "Luis", "Sevilla")),
        new TypeToken<List<ClienteDto>>() {}.getType());
dtos.forEach(d -> System.out.println(d.getNombreCompleto() + " vive en " + d.getDireccionCiudad()));
Ana vive en Valencia
Luis vive en Sevilla
  • STRICT exige que los nombres encajen por completo; la estrategia por defecto (STANDARD) es más permisiva y a veces empareja campos que no tocan.
  • Con STRICT, el aplanado automático deja de funcionar, por eso direccionCiudad se declara explícitamente.
  • validate() lanza una excepción si un campo del destino no tiene origen. Ponlo en un test o al arrancar la aplicación y los errores de mapeo aparecerán antes de llegar a producción.
  • Para listas, Java borra los genéricos en ejecución, de ahí el TypeToken.

En Spring Boot

Declara un único ModelMapper como bean y configúralo una vez; es seguro compartirlo una vez configurado:

@Bean
ModelMapper modelMapper() {
    ModelMapper mapper = new ModelMapper();
    mapper.getConfiguration().setMatchingStrategy(MatchingStrategies.STRICT);
    return mapper;
}

Después lo inyectas en tus servicios. Más sobre beans en @Configuration y @Bean.

ModelMapper, MapStruct o a mano

ModelMapperMapStructA mano
Cómo funcionaReflexión en ejecuciónGenera código al compilarCódigo propio
Errores de mapeoEn ejecución (o con validate())Al compilarAl compilar
RendimientoEl más lentoComo el código a manoEl mejor
ConfiguraciónMínimaInterfaz con anotacionesNinguna
RecordsLimitado (necesita setters en el destino)SíSí

Para proyectos nuevos solemos recomendar MapStruct: los errores aparecen al compilar y funciona con records. Lo tienes en MapStruct en Java. ModelMapper sigue siendo práctico para prototipos o proyectos que ya lo usan. Y para tres campos, un método estático ClienteDto.from(cliente) escrito a mano es lo más claro.

Preguntas frecuentes

¿ModelMapper funciona con records?

Como origen, sí. Como destino, no de serie, porque los records no tienen constructor vacío ni setters. Con records como DTO, usa MapStruct o un método de fábrica.

¿Cómo excluyo un campo?

En el TypeMap, con m.skip(ClienteDto::setCampo).

¿Es seguro con varios hilos?

Sí, una vez configurado. No añadas TypeMap mientras otros hilos lo están usando.

Sigue aprendiendo

DTOs, validación y el diseño de las capas de una API se trabajan en el curso de Spring Boot Web. Cuando los DTOs vienen de entidades JPA, revisa relaciones en JPA.

modelmapper dto java spring boot mapeo de objetos mapstruct

Newsletter Semanal de Java

Cada viernes recibe lo más nuevo del ecosistema Java: frameworks, herramientas y mejores prácticas.

Sin spam. Cancela cuando quieras.

Compartir artículo