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 unTypeMap. UsaMatchingStrategies.STRICTyvalidate()para que un campo sin mapear sea un error y no unnullsilencioso. 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
STRICTexige 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 esodireccionCiudadse 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
| ModelMapper | MapStruct | A mano | |
|---|---|---|---|
| Cómo funciona | Reflexión en ejecución | Genera código al compilar | Código propio |
| Errores de mapeo | En ejecución (o con validate()) | Al compilar | Al compilar |
| Rendimiento | El más lento | Como el código a mano | El mejor |
| Configuración | Mínima | Interfaz con anotaciones | Ninguna |
| Records | Limitado (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.
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.