Mapping von Java-Datenstrukturen mit der Mapstruct-Library

Einleitung

In der Softwareentwicklung ist das Mapping von Datenstrukturen eine gängige Anforderung, insbesondere in Anwendungen, die Daten zwischen verschiedenen Schichten austauschen. Java-Entwickler stehen häufig vor der Herausforderung, komplexe Objekte von einer Form in eine andere zu transformieren. Dabei kann es sich beispielsweise um die Umwandlung von Datenbankentitäten in DTOs (Data Transfer Objects) handeln oder um die Transformation von API-Requests in Domänenobjekte.

Um diesen Prozess effizienter und weniger fehleranfällig zu gestalten, bietet die Mapstruct-Library eine leistungsstarke und flexible Lösung. Mapstruct ist eine Java-basierte Annotation-Processor-Bibliothek, die zur Kompilierzeit Mapping-Code generiert. In diesem Artikel werden wir die grundlegenden Konzepte von Mapstruct, deren Konfiguration und einige erweiterte Funktionen durchgehen.

Grundlagen von Mapstruct

Mapstruct zielt darauf ab, den mühsamen und fehleranfälligen Prozess des Schreibens von Mapping-Code zu automatisieren. Dies wird durch den Einsatz von Annotationen erreicht, die an den Mapping-Schnittstellen und Methoden definiert werden. Diese Annotationen werden zur Kompilierzeit verarbeitet, um den notwendigen Code zu generieren, der die Mappings ausführt.

Installation und Konfiguration

Um Mapstruct in einem Java-Projekt zu verwenden, müssen zunächst die notwendigen Abhängigkeiten in der pom.xml (für Maven) oder build.gradle (für Gradle) hinzugefügt werden. Ein Beispiel für Maven:

<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.5.0</version>
</dependency>
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct-processor</artifactId>
    <version>1.5.0</version>
    <scope>provided</scope>
</dependency>Code-Sprache: HTML, XML (xml)

Für Gradle sieht die Konfiguration ähnlich aus:

implementation 'org.mapstruct:mapstruct:1.5.0'
annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.0'Code-Sprache: JavaScript (javascript)

Erstellen von Mapper-Interfaces

Ein grundlegendes Beispiel für einen Mapper könnte die Transformation zwischen einem User-Entität und einem UserDTO sein. Zuerst definieren wir die beiden Klassen:

public class User {
    private Long id;
    private String name;
    private String email;
    // Getter und Setter
}

public class UserDTO {
    private Long id;
    private String name;
    // Getter und Setter
}Code-Sprache: PHP (php)

Nun definieren wir ein Mapper-Interface, das Mapstruct verwendet, um die Konvertierung durchzuführen:

import org.mapstruct.Mapper;
import org.mapstruct.factory.Mappers;

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    UserDTO userToUserDTO(User user);
    User userDTOToUser(UserDTO userDTO);
}Code-Sprache: JavaScript (javascript)

Durch die Annotation @Mapper und die Methode Mappers.getMapper(UserMapper.class) wird Mapstruct angewiesen, die Implementierung dieses Interfaces zur Kompilierzeit zu generieren.

Nutzung des Mappers

Die Verwendung des generierten Mappers ist unkompliziert:

public class UserService {
    public UserDTO getUserDTO(User user) {
        return UserMapper.INSTANCE.userToUserDTO(user);
    }
}Code-Sprache: PHP (php)

Erweiterte Mapstruct-Funktionen

Neben den grundlegenden Mappings bietet Mapstruct eine Reihe erweiterter Funktionen, um komplexere Anforderungen abzudecken.

Anpassung von Mappings

Manchmal erfordern Mappings benutzerdefinierte Logik oder spezifische Anpassungen. Dies kann durch die Verwendung von @Mapping-Annotationen erreicht werden:

import org.mapstruct.Mapping;

@Mapper
public interface UserMapper {
    @Mapping(source = "email", target = "contactEmail")
    UserDTO userToUserDTO(User user);
}Code-Sprache: CSS (css)

In diesem Beispiel wird das email-Feld des User-Objekts auf das contactEmail-Feld des UserDTO-Objekts gemappt.

Verwendung von Expression und Default Values

Für komplexere Transformationen kann die expression-Eigenschaft der @Mapping-Annotation verwendet werden:

@Mapping(target = "fullName", expression = "java(user.getFirstName() + ' ' + user.getLastName())")
UserDTO userToUserDTO(User user);Code-Sprache: CSS (css)

Auch Standardwerte können gesetzt werden, falls ein Quellfeld null ist:

@Mapping(target = "status", defaultValue = "ACTIVE")
UserDTO userToUserDTO(User user);Code-Sprache: CSS (css)

Collection Mappings

Mapstruct unterstützt auch das Mapping von Collections wie Listen und Sets:

@Mapper
public interface UserMapper {
    List<UserDTO> usersToUserDTOs(List<User> users);
}Code-Sprache: PHP (php)

Nested Mappings

Bei verschachtelten Objekten kann Mapstruct automatisch die entsprechenden Unterobjekte mappen:

public class Address {
    private String street;
    private String city;
    // Getter und Setter
}

public class User {
    private Long id;
    private String name;
    private Address address;
    // Getter und Setter
}

public class UserDTO {
    private Long id;
    private String name;
    private String street;
    private String city;
    // Getter und Setter
}

@Mapper
public interface UserMapper {
    @Mapping(source = "address.street", target = "street")
    @Mapping(source = "address.city", target = "city")
    UserDTO userToUserDTO(User user);
}Code-Sprache: PHP (php)

In diesem Beispiel werden die Felder des verschachtelten Address-Objekts auf die entsprechenden Felder im UserDTO gemappt.

Vor- und Nachbearbeitungsmethoden

Manchmal ist es notwendig, zusätzliche Logik vor oder nach dem Mapping-Prozess auszuführen. Hierfür bietet Mapstruct die @BeforeMapping und @AfterMapping-Annotationen:

@Mapper
public interface UserMapper {

    @AfterMapping
    default void afterMapping(User user, @MappingTarget UserDTO userDTO) {
        userDTO.setFullName(user.getFirstName() + " " + user.getLastName());
    }
}Code-Sprache: CSS (css)

Fazit

Mapstruct ist eine leistungsstarke Bibliothek, die den Aufwand für das Schreiben und Pflegen von Mapping-Code erheblich reduziert. Durch die Annotation-basierte Konfiguration und die automatische Codegenerierung zur Kompilierzeit wird der Mapping-Prozess nicht nur schneller, sondern auch weniger fehleranfällig. Die Unterstützung für komplexe Mappings, benutzerdefinierte Logik und Erweiterbarkeit machen Mapstruct zu einer wertvollen Ergänzung im Werkzeugkasten eines jeden Java-Entwicklers.

Obwohl dieser Artikel nur die grundlegenden und einige erweiterte Funktionen von Mapstruct behandelt, gibt es noch viele weitere Aspekte zu entdecken, wie die Integration mit anderen Frameworks, komplexere Mapping-Strategien und Optimierungen. Entwickler sind daher eingeladen, die offizielle Dokumentation und weitere Ressourcen zu konsultieren, um das volle Potenzial von Mapstruct auszuschöpfen.