MapStruct para Java: guía completa con ejemplos

¿Qué es MapStruct y para qué sirve?

MapStruct es un generador de código para Java que crea automáticamente implementaciones de mapeadores (convertidores) entre objetos de diferentes tipos. En el desarrollo moderno de Java, surge frecuentemente la necesidad de convertir un objeto en otro: Entity a DTO, DTO a VO, una respuesta de API a otro modelo, etc. Escribir este código manualmente es un trabajo tedioso, laborioso y propenso a errores. MapStruct resuelve este problema generando todo el código repetitivo (boilerplate) en tiempo de compilación.

Principales ventajas de MapStruct:

\n
• Rendimiento: Generación de código en tiempo de compilación (compile-time). Sin reflexión, sin pérdidas de rendimiento en tiempo de ejecución. MapStruct funciona tan rápido como si hubiera escrito el mapeo manualmente.
\n
• Seguridad de tipos: Todos los errores (incompatibilidad de tipos, campos faltantes) se detectan en tiempo de compilación, no en tiempo de ejecución.
\n
• Simplicidad: Mínima configuración. Basta con definir una interfaz o clase abstracta con métodos de mapeo, y MapStruct generará la implementación automáticamente.
\n
• Flexibilidad: Soporte para mapeos complejos, conversión de tipos, uso de expresiones, llamadas a métodos e integración con otras bibliotecas (Lombok, Spring, etc.).
\n
• Código limpio: El código de mapeo está separado de la lógica de negocio, lo que lo hace más legible y mantenible.
\n

MapStruct es especialmente útil en arquitecturas multicapa (Controller-Service-Repository), donde a menudo se requiere convertir objetos entre capas.

Instalación de MapStruct

MapStruct no se instala mediante pip o npm, ya que es una biblioteca para Java. Para agregar MapStruct a su proyecto se utiliza el sistema de compilación Maven o Gradle.

Instalación mediante Maven

Agregue las siguientes dependencias a su archivo pom.xml:

<dependencies>\n    <!-- Biblioteca principal de MapStruct -->\n    <dependency>\n        <groupId>org.mapstruct</groupId>\n        <artifactId>mapstruct</artifactId>\n        <version>1.5.5.Final</version>\n    </dependency>\n\n    <!-- Procesador de anotaciones (para generación de código) -->\n    <dependency>\n        <groupId>org.mapstruct</groupId>\n        <artifactId>mapstruct-processor</artifactId>\n        <version>1.5.5.Final</version>\n        <scope>provided</scope>\n    </dependency>\n</dependencies>

Instalación mediante Gradle

Para Gradle, agregue al archivo build.gradle:

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

Importante: Asegúrese de que la versión de mapstruct-processor coincida con la versión de mapstruct. Después de agregar las dependencias, ejecute la compilación del proyecto (por ejemplo, mvn clean compile) para que MapStruct genere las implementaciones de los mapeadores.

Inicio rápido con un ejemplo de código

Vamos a crear un mapeador simple que convierta un objeto Car (Entity) en un objeto CarDto (DTO).

Paso 1: Defina las clases de origen y destino

// Car.java\npublic class Car {\n    private String make;\n    private int numberOfSeats;\n    private CarType type;\n\n    // constructores, getters, setters\n    public Car() {}\n\n    public Car(String make, int numberOfSeats, CarType type) {\n        this.make = make;\n        this.numberOfSeats = numberOfSeats;\n        this.type = type;\n    }\n\n    public String getMake() { return make; }\n    public void setMake(String make) { this.make = make; }\n    public int getNumberOfSeats() { return numberOfSeats; }\n    public void setNumberOfSeats(