MapStruct for Java: Complete Guide with Examples

What is MapStruct and why is it needed?

MapStruct is a code generator for Java that automatically creates mapper implementations (transformers) between objects of different types. In modern Java development, there is often a need to transform one object into another: Entity to DTO, DTO to VO, one API response to another model, and so on. Writing such code manually is tedious, time-consuming, and error-prone. MapStruct solves this problem by generating all the boilerplate code at compile time.

Key advantages of MapStruct:

\n
• Performance: Code generation at compile time. No reflection, no runtime performance loss. MapStruct works as fast as if you wrote the mapping manually.
\n
• Type safety: All errors (type mismatches, missing fields) are detected at compile time, not at runtime.
\n
• Simplicity: Minimal configuration. Just define an interface or abstract class with mapping methods, and MapStruct will generate the implementation automatically.
\n
• Flexibility: Support for complex mappings, type conversions, expressions, method calls, and integration with other libraries (Lombok, Spring, etc.).
\n
• Clean code: Mapping code is separated from business logic, making it more readable and maintainable.
\n

MapStruct is especially useful in multi-layered architectures (Controller-Service-Repository), where objects often need to be transformed between layers.

Installing MapStruct

MapStruct is not installed via pip or npm, as it is a Java library. To add MapStruct to your project, use the Maven or Gradle build system.

Installation via Maven

Add the following dependencies to your pom.xml file:

<dependencies>\n    <!-- Main MapStruct library -->\n    <dependency>\n        <groupId>org.mapstruct</groupId>\n        <artifactId>mapstruct</artifactId>\n        <version>1.5.5.Final</version>\n    </dependency>\n\n    <!-- Annotation processor (for code generation) -->\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>

Installation via Gradle

For Gradle, add to your build.gradle file:

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

Important: Make sure the version of mapstruct-processor matches the version of mapstruct. After adding the dependencies, build your project (e.g., mvn clean compile) so that MapStruct generates the mapper implementations.

Quick start with code example

Let's create a simple mapper that transforms a Car object (Entity) into a CarDto object (DTO).

Step 1: Define the source and target classes

// Car.java\npublic class Car {\n    private String make;\n    private int numberOfSeats;\n    private CarType type;\n\n    // constructors, 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(