MapStruct — générer les mappers DTO ↔ entité à la compilation

1📖 Glossaire — le vocabulaire de base

• Annotation processor — programme branché sur javac qui lit les annotations et génère du code source avant la compilation finale.
• Mapper — interface (ou classe abstraite) annotée @Mapper qui déclare les méthodes de conversion.
• MapperImpl — classe concrète générée par MapStruct dans target/generated-sources/annotations.
• Source / target — l'objet d'entrée et l'objet de sortie d'une méthode de mapping.
• Component model — façon d'instancier le mapper : default (via Mappers.getMapper), spring, cdi, jsr330, jakarta.
• Unmapped target property — champ de l'objet cible qu'aucune règle n'alimente.
• Qualifier — annotation (@Named ou custom) qui désigne une méthode de conversion précise quand plusieurs sont possibles.
• Presence check — test qui décide si un champ source est "présent" et doit être copié ; par défaut != null, remplaçable par @Condition.
• Décorateur — classe qui enveloppe le mapper généré pour ajouter de la logique avant ou après une méthode.

2Comment ça marche : du code généré, pas de réflexion

MapStruct s'exécute pendant la compilation. Le flux est le suivant.

flowchart LR
    A["OrderMapper.java<br/>(interface + annotations)"] --> B["javac"]
    B --> C["mapstruct-processor<br/>(annotation processor)"]
    C --> D["OrderMapperImpl.java<br/>(généré, lisible)"]
    D --> B2["javac"]
    B2 --> E["OrderMapperImpl.class"]
    C -. "champ cible sans source,<br/>type incompatible" .-> F["Erreur de compilation"]

Un exemple minimal. L'entité et le DTO :

public class Order {
    private Long id;
    private String customerEmail;
    private BigDecimal totalAmount;
    private LocalDateTime createdAt;
    // getters / setters
}

public record OrderDto(Long id, String email, BigDecimal total, String createdAt) {}

Le mapper :

@Mapper
public interface OrderMapper {

    @Mapping(target = "email", source = "customerEmail")
    @Mapping(target = "total", source = "totalAmount")
    @Mapping(target = "createdAt", dateFormat = "yyyy-MM-dd'T'HH:mm:ss")
    OrderDto toDto(Order order);
}

Le code généré (extrait de OrderMapperImpl) :

@Generated("org.mapstruct.ap.MappingProcessor")
public class OrderMapperImpl implements OrderMapper {

    @Override
    public OrderDto toDto(Order order) {
        if ( order == null ) {          // ✓ null-check automatique sur la source
            return null;
        }
        Long id = order.getId();
        String email = order.getCustomerEmail();
        BigDecimal total = order.getTotalAmount();
        String createdAt = null;
        if ( order.getCreatedAt() != null ) {
            createdAt = DateTimeFormatter.ofPattern( "yyyy-MM-dd'T'HH:mm:ss" ).format( order.getCreatedAt() );
        }
        return new OrderDto( id, email, total, createdAt );   // ✓ record : constructeur canonique
    }
}

Ce code est du Java ordinaire. On peut poser un breakpoint dedans. On peut le lire dans target/generated-sources/annotations. Aucune bibliothèque n'est chargée à l'exécution : le jar mapstruct ne contient que les annotations.

3Configuration Maven, avec Lombok

Deux artefacts : mapstruct (annotations, scope compile) et mapstruct-processor (uniquement dans annotationProcessorPaths). Version stable actuelle : 1.6.3.

<properties>
    <mapstruct.version>1.6.3</mapstruct.version>
    <lombok.version>1.18.34</lombok.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>${mapstruct.version}</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <annotationProcessorPaths>
                    <!-- ⚠️ Lombok AVANT MapStruct : MapStruct doit voir les getters générés -->
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${lombok.version}</version>
                    </path>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${mapstruct.version}</version>
                    </path>
                    <!-- ✓ obligatoire avec Lombok >= 1.18.16 -->
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok-mapstruct-binding</artifactId>
                        <version>0.2.0</version>
                    </path>
                </annotationProcessorPaths>
                <compilerArgs>
                    <!-- ✓ options globales, évite de les répéter sur chaque @Mapper -->
                    <arg>-Amapstruct.defaultComponentModel=spring</arg>
                    <arg>-Amapstruct.unmappedTargetPolicy=ERROR</arg>
                </compilerArgs>
            </configuration>
        </plugin>
    </plugins>
</build>

4Les mappings de base

Conversions implicites

MapStruct convertit tout seul, sans annotation :

• Types primitifs et wrappers (int ↔ Integer, long ↔ int avec cast).
• Nombres ↔ String, avec numberFormat si besoin.
• Enum ↔ String (par name()).
• Dates java.time ↔ String avec dateFormat, java.util.Date ↔ LocalDateTime, etc.
• String ↔ UUID, BigDecimal ↔ BigInteger.

Les attributs de @Mapping

@Mapper
public interface CustomerMapper {

    @Mapping(target = "fullName", expression = "java(customer.getFirstName() + \" \" + customer.getLastName())")
    @Mapping(target = "status", constant = "ACTIVE")          // valeur fixe
    @Mapping(target = "country", source = "address.country", defaultValue = "FR")  // fallback si null
    @Mapping(target = "internalNotes", ignore = true)        // ✓ explicite : on ne mappe pas
    @Mapping(target = "zipCode", source = "address.postalCode")   // ✓ chemin imbriqué
    CustomerDto toDto(Customer customer);
}

5Mappings composés

Objets imbriqués et réutilisation de mappers

MapStruct cherche une méthode existante pour chaque sous-type. Il la trouve dans le mapper courant ou dans les mappers déclarés avec uses.

@Mapper
public interface AddressMapper {
    AddressDto toDto(Address address);
}

@Mapper(uses = AddressMapper.class)   // ✓ délégation, injectée si componentModel = spring
public interface CustomerMapper {
    CustomerDto toDto(Customer customer);   // customer.address → AddressMapper.toDto
}

Si aucune méthode n'existe pour un sous-type, MapStruct en génère une automatiquement, en privé, dans MapperImpl. C'est pratique mais peu contrôlable. Une méthode explicite est préférable dès que le sous-type a des règles.

Aplatir et imbriquer : target = "." et source = "."

Le point veut dire « l'objet entier », pas un de ses champs. Il s'emploie dans deux sens.

Aplatir avec target = "." (depuis 1.4). La source a un sous-objet. La cible est plate. On veut verser les champs du sous-objet directement dans la cible.

public class Customer {
    private String name;
    private Address address;   // street, city, zipCode
}

public record CustomerFlatDto(String name, String street, String city, String zipCode) {}

@Mapper
public interface CustomerMapper {
    @Mapping(target = ".", source = "address")   // ✓ address.street → street, address.city → city, address.zipCode → zipCode
    CustomerFlatDto toFlat(Customer customer);
}

Sans le point, il faudrait un @Mapping(target = "street", source = "address.street") par champ. Avec, MapStruct fait la correspondance par nom entre les champs de address et ceux de la cible. Si un même nom existe à deux niveaux (par exemple name dans Customer et dans Address), MapStruct signale une ambiguïté. Il faut alors trancher avec un @Mapping explicite.

Imbriquer avec source = ".". C'est l'inverse. La source est plate. La cible a des sous-objets. Chaque sous-objet doit être construit à partir de la source entière.

public record ShipmentEvent(String orderId, String carrier, String trackingUrl, LocalDateTime shippedAt) {}

public record ShipmentDto(OrderRef order, CarrierInfo carrier) {}
public record OrderRef(String id) {}
public record CarrierInfo(String name, String trackingUrl) {}

@Mapper
public interface ShipmentMapper {

    @Mapping(target = "order", source = ".")      // ✓ l'événement entier → toOrderRef
    @Mapping(target = "carrier", source = ".")    // ✓ l'événement entier → toCarrierInfo
    ShipmentDto toDto(ShipmentEvent event);

    @Mapping(target = "id", source = "orderId")
    OrderRef toOrderRef(ShipmentEvent event);

    @Mapping(target = "name", source = "carrier")
    CarrierInfo toCarrierInfo(ShipmentEvent event);
}

Comment MapStruct choisit la méthode : par le type de retour. Pour order, il cherche une méthode qui prend ShipmentEvent et renvoie OrderRef. Pour carrier, une qui renvoie CarrierInfo. Si deux champs cibles ont le même type, les deux méthodes candidates sont ambiguës. Il faut alors @Named sur les méthodes et qualifiedByName sur les @Mapping.

Un usage utile : source = "." avec une @Condition. La condition reçoit alors l'objet source entier, et peut décider à partir de plusieurs champs.

@Mapping(target = "carrier", source = ".", conditionQualifiedByName = "isShipped")
ShipmentDto toDto(ShipmentEvent event);

@Condition
@Named("isShipped")
default boolean isShipped(ShipmentEvent event) {
    return event.carrier() != null && event.shippedAt() != null;   // ✓ deux champs consultés
}

Collections et Map

Une méthode qui mappe Order → OrderDto suffit pour que List<Order> → List<OrderDto> fonctionne. Il faut juste déclarer la signature.

@Mapper
public interface OrderMapper {
    OrderDto toDto(Order order);
    List<OrderDto> toDtos(List<Order> orders);          // ✓ itère et appelle toDto
    Map<String, OrderDto> toDtoById(Map<String, Order> orders);
}

Set, Collection, Iterable et les Stream sont supportés de la même façon.

Enums avec @ValueMapping

@Mapper
public interface StatusMapper {

    @ValueMapping(target = "OPEN", source = "CREATED")
    @ValueMapping(target = "OPEN", source = "CONFIRMED")
    @ValueMapping(target = "CLOSED", source = "SHIPPED")
    @ValueMapping(target = MappingConstants.NULL, source = MappingConstants.ANY_REMAINING)  // ✓ tout le reste → null
    PublicStatus toPublic(InternalStatus status);
}

Sans ANY_REMAINING ni ANY_UNMAPPED, une valeur source inconnue lève une IllegalArgumentException à l'exécution. MapStruct vérifie à la compilation que chaque constante source est couverte, et échoue sinon.

Plusieurs sources vers une cible

@Mapper
public interface ShipmentMapper {

    @Mapping(target = "orderId", source = "order.id")
    @Mapping(target = "carrier", source = "carrierInfo.name")
    @Mapping(target = "trackingUrl", source = "carrierInfo.url")
    ShipmentDto toDto(Order order, CarrierInfo carrierInfo);   // ✓ deux paramètres
}

Quand plusieurs sources ont un champ du même nom, il faut qualifier avec le nom du paramètre, sinon erreur de compilation pour ambiguïté.

Modifier un objet déjà en mémoire : @MappingTarget

Jusqu'ici, chaque méthode crée un objet neuf : le code généré fait new OrderDto(...).

@MappingTarget fait autre chose. Il n'y a pas de new. On passe en paramètre un objet qui existe déjà, et MapStruct appelle ses setters dessus. La méthode renvoie void (ou le même objet).

Le cas typique est un PATCH /customers/42. L'objet "existant", c'est l'entité chargée depuis la base. Hibernate la suit (elle est managed). On veut la modifier, pas en créer une deuxième.

Customer customer = customerRepository.findById(42L).orElseThrow();  // 1. l'objet existe déjà, chargé depuis la base
customerMapper.updateFromDto(dto, customer);                          // 2. MapStruct fait customer.setEmail(dto.email()), etc.
// 3. fin de transaction : Hibernate détecte les changements et génère l'UPDATE

Si on faisait Customer c = mapper.toEntity(dto) à la place, on aurait un second objet, sans id, inconnu de Hibernate. Le save ferait un INSERT, ou écraserait tous les champs.

Le mapper :

@Mapper(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
public interface CustomerMapper {

    @Mapping(target = "id", ignore = true)         // ✓ jamais écrasé
    @Mapping(target = "createdAt", ignore = true)
    void updateFromDto(CustomerPatchDto dto, @MappingTarget Customer customer);
}

sequenceDiagram
    participant C as Controller
    participant S as Service (@Transactional)
    participant R as Repository
    participant M as CustomerMapperImpl
    C->>S: patch(id, dto)
    S->>R: findById(id)
    R-->>S: Customer (managed)
    S->>M: updateFromDto(dto, customer)
    Note over M: pour chaque champ non null du dto<br/>customer.setX(dto.x())
    M-->>S: void
    Note over S,R: commit → Hibernate dirty checking<br/>génère l'UPDATE

Le DTO d'un PATCH n'envoie que les champs à changer. Les autres sont null. Avec IGNORE, un champ null dans le DTO ne touche pas l'entité. Sans cette stratégie, la valeur par défaut SET_TO_NULL écrase le champ avec null. Pour un PATCH, c'est presque toujours un bug.

Décider si un champ est copié : @Condition

Par défaut, MapStruct copie un champ si sa valeur source est != null. C'est le presence check. @Condition (depuis 1.5) permet de remplacer ce test par une méthode à soi.

Cas concret : une chaîne vide venue d'un formulaire ne doit pas écraser une valeur en base.

@Mapper(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
public interface CustomerMapper {

    void updateFromDto(CustomerPatchDto dto, @MappingTarget Customer customer);

    @Condition
    default boolean isNotBlank(String value) {     // ✓ s'applique à tous les champs String du mapper
        return value != null && !value.isBlank();
    }
}

Code généré pour un champ String :

if ( isNotBlank( dto.getEmail() ) ) {     // ✓ remplace le test != null
    customer.setEmail( dto.getEmail() );
}

Ce qu'il faut savoir :

• La méthode @Condition renvoie boolean. Elle est choisie par le type du champ source. Une condition sur String s'applique à tous les champs String du mapper, y compris ceux déclarés dans uses.
• Pour cibler un seul champ : @Named("emailPresent") sur la condition, et @Mapping(target = "email", conditionQualifiedByName = "emailPresent").
• La méthode peut recevoir en plus le bean source entier, un @Context, et depuis 1.6 le nom du champ via @SourcePropertyName String ou @TargetPropertyName String. Cela permet une seule condition générique qui décide selon le nom du champ.
• Depuis 1.6, @SourceParameterCondition marque une condition qui porte sur le paramètre source entier, pas sur un champ. Utile pour ignorer un sous-objet vide.
• MapStruct reconnaît aussi automatiquement les méthodes hasXxx() du bean source (style Protobuf) comme presence check, sans annotation.

Records, builders et immutables

MapStruct sait construire un record par son constructeur canonique. Il détecte aussi les builders (Lombok @Builder, Immutables, AutoValue) via une méthode statique builder() et une méthode build(). Pour les classes sans setter, il cherche un constructeur avec les bons paramètres, ou celui annoté @Default.

Hooks : @BeforeMapping, @AfterMapping, @Context

@Mapper
public abstract class OrderMapper {

    public abstract OrderDto toDto(Order order, @Context Locale locale);   // ✓ @Context : passé, jamais mappé

    @AfterMapping
    protected void computeLabel(Order order, @MappingTarget OrderDto.Builder dto, @Context Locale locale) {
        dto.label(LabelFormatter.format(order, locale));
    }
}

Une classe abstraite permet d'injecter des dépendances et de garder de l'état. Les hooks sont appelés dans le code généré, dans l'ordre : @BeforeMapping, mapping, @AfterMapping.

Choisir une conversion : @Named et qualifiedByName

@Mapper
public interface ProductMapper {

    @Mapping(target = "price", source = "priceCents", qualifiedByName = "centsToEuros")
    ProductDto toDto(Product product);

    @Named("centsToEuros")
    default BigDecimal centsToEuros(long cents) {
        return BigDecimal.valueOf(cents, 2);
    }
}

Sans @Named, une méthode default qui convertit long → BigDecimal serait appliquée à tous les champs long → BigDecimal du mapper. Le qualifier rend le choix explicite.

6Réutiliser et spécialiser un mapper

Un mapper réel a vite dix méthodes. Beaucoup se ressemblent. Cette section montre les outils pour ne pas répéter les règles, et pour gérer les cas que le mapping simple ne couvre pas.

Ne pas réécrire les règles à l'envers : @InheritInverseConfiguration

Problème : toDto a trois @Mapping. Pour toEntity, il faut les mêmes, mais avec source et target inversés. On les recopie, et un jour on en oublie une.

Solution : @InheritInverseConfiguration lit les @Mapping d'une méthode qui va dans l'autre sens, et les retourne.

@Mapper
public interface OrderMapper {

    @Mapping(target = "email", source = "customerEmail")
    @Mapping(target = "total", source = "totalAmount")
    OrderDto toDto(Order order);

    @InheritInverseConfiguration          // ✓ email → customerEmail, total → totalAmount
    @Mapping(target = "id", ignore = true) // on peut ajouter des règles par dessus
    Order toEntity(OrderDto dto);
}

Ce qui est inversé : les source / target. Ce qui ne l'est pas : constant, expression, ignore. Une constante n'a pas de sens à l'envers. Un ignore sur toDto ignore un champ du DTO, ce n'est pas un champ de l'entité. Il faut donc redéclarer ces cas.

Il existe aussi @InheritConfiguration. Elle copie les règles d'une méthode qui va dans le même sens. Cas typique : la méthode update hérite des @Mapping de la méthode create.

@Mapping(target = "id", ignore = true)
@Mapping(target = "email", source = "customerEmail")
Order toEntity(OrderDto dto);

@InheritConfiguration(name = "toEntity")   // ✓ mêmes règles, pas de copier-coller
void update(OrderDto dto, @MappingTarget Order order);

Quand il n'y a qu'une méthode candidate, name est facultatif. Si plusieurs méthodes correspondent, il faut la nommer, sinon erreur de compilation.

Tout ignorer sauf ce qu'on déclare : @BeanMapping(ignoreByDefault = true)

Par défaut, MapStruct essaie de mapper tous les champs de la cible. Avec unmappedTargetPolicy = ERROR, il faut donc écrire ignore = true sur chaque champ qu'on ne veut pas.

Parfois c'est l'inverse qu'on veut. On a une entité avec trente champs. Le PATCH n'en touche que deux. Écrire vingt-huit ignore est absurde.

ignoreByDefault = true retourne la règle : rien n'est mappé, sauf ce qui a un @Mapping explicite.

@BeanMapping(ignoreByDefault = true)
@Mapping(target = "email", source = "email")     // ✓ seuls ces deux champs sont copiés
@Mapping(target = "phone", source = "phone")
void updateContact(ContactPatchDto dto, @MappingTarget Customer customer);

@BeanMapping porte d'autres options utiles au niveau de la méthode : nullValuePropertyMappingStrategy, qualifiedByName (pour appliquer une méthode @Named à toute la méthode), resultType (choisir la sous-classe à instancier).

Gérer les hiérarchies de classes : @SubclassMapping

Problème : Animal a deux sous-classes, Dog et Cat. On veut AnimalDto toDto(Animal animal). Mais un Dog doit devenir un DogDto, avec ses champs propres. MapStruct ne le sait pas tout seul : il ne voit que le type déclaré, Animal.

@SubclassMapping (depuis 1.5) déclare la correspondance par sous-classe. Le code généré teste le type réel avec instanceof.

@Mapper
public interface AnimalMapper {

    @SubclassMapping(source = Dog.class, target = DogDto.class)
    @SubclassMapping(source = Cat.class, target = CatDto.class)
    AnimalDto toDto(Animal animal);

    DogDto toDogDto(Dog dog);   // ✓ utilisées par le routage
    CatDto toCatDto(Cat cat);
}

Code généré :

if ( animal instanceof Dog ) {
    return toDogDto( (Dog) animal );
}
else if ( animal instanceof Cat ) {
    return toCatDto( (Cat) animal );
}
else {
    throw new IllegalArgumentException( "Not all subclasses are supported for this mapping. Missing for " + animal.getClass() );
}

Ce qu'il faut savoir :

• L'ordre des @SubclassMapping compte. Si Puppy extends Dog, déclarer Puppy avant Dog, sinon le instanceof Dog attrape tout.
• Un type non déclaré lève une exception à l'exécution. C'est un point aveugle du contrôle à la compilation.
• Avec une classe sealed (Java 17), subclassExhaustiveStrategy = COMPILE_ERROR sur @BeanMapping transforme cette exception en erreur de compilation. C'est la seule façon de rendre le routage sûr au build.

Mapper des enums par transformation de nom : @EnumMapping

Cas fréquent : un enum interne ORDER_CREATED, ORDER_SHIPPED et un enum public CREATED, SHIPPED. Écrire un @ValueMapping par constante marche, mais c'est long et fragile.

@EnumMapping (depuis 1.5) applique une règle sur le nom.

@EnumMapping(nameTransformationStrategy = MappingConstants.STRIP_PREFIX, configuration = "ORDER_")
PublicStatus toPublic(InternalStatus status);   // ORDER_CREATED → CREATED

Stratégies disponibles : PREFIX, SUFFIX (ajouter), STRIP_PREFIX, STRIP_SUFFIX (retirer), CASE (upper, lower, capital). MapStruct vérifie toujours à la compilation que chaque constante source a une cible après transformation.

Contrôler la création de l'objet cible : @ObjectFactory

Par défaut, MapStruct crée la cible avec new. Parfois on veut décider soi-même comment l'objet est obtenu.

Exemple : si le DTO a un id, on veut l'entité existante depuis la base, pas un objet neuf. Une méthode annotée @ObjectFactory qui renvoie le type cible est appelée à la place du new.

@Mapper(componentModel = "spring")
public abstract class CustomerMapper {

    @Autowired
    protected CustomerRepository repository;

    @ObjectFactory
    protected Customer resolve(CustomerDto dto) {
        if ( dto.id() != null ) {
            return repository.findById( dto.id() ).orElseGet( Customer::new );  // ✓ objet existant
        }
        return new Customer();
    }

    public abstract Customer toEntity(CustomerDto dto);   // utilise resolve() au lieu de new
}

Ce qu'il faut savoir :

• La factory reçoit en paramètre la source (facultatif), et peut recevoir un @Context ou un @TargetType Class<T> pour une factory générique.
• Sur une méthode @MappingTarget, la factory n'est pas appelée : l'objet est déjà fourni.
• Un accès base dans un mapper est discutable. C'est pratique, mais cela cache une requête SQL dans ce qui ressemble à une copie de champs. À réserver aux cas simples, et à documenter.

Envelopper une méthode générée : @DecoratedWith

@AfterMapping permet d'ajouter du code après le mapping. Mais parfois on veut plus : faire quelque chose avant et après, ou remplacer complètement une méthode tout en gardant les autres générées.

@DecoratedWith désigne une classe abstraite qui implémente le mapper. MapStruct injecte le mapper généré dans le décorateur. Les méthodes que le décorateur ne redéfinit pas sont déléguées au code généré.

@Mapper(componentModel = "spring")
@DecoratedWith(OrderMapperDecorator.class)
public interface OrderMapper {
    OrderDto toDto(Order order);
    List<OrderDto> toDtos(List<Order> orders);
}

public abstract class OrderMapperDecorator implements OrderMapper {

    @Autowired
    @Qualifier("delegate")            // ✓ le mapper généré, nommé "delegate" par MapStruct
    private OrderMapper delegate;

    @Override
    public OrderDto toDto(Order order) {
        OrderDto dto = delegate.toDto( order );          // 1. mapping généré
        return dto.withLabel( LabelFormatter.format( order ) );   // 2. logique ajoutée
    }
    // toDtos n'est pas redéfini : délégué tel quel
}

Avec componentModel = "spring", le décorateur devient le bean @Primary. C'est lui qu'on injecte partout, sans changer le code appelant.

Règle simple pour choisir :

• Ajouter un calcul après le mapping : @AfterMapping.
• Faire un traitement avant, ou remplacer une méthode : @DecoratedWith.
• Avoir des dépendances injectées dans le mapper : classe abstraite, sans décorateur.

Les autres, en une ligne

7Politiques : rendre le silence impossible

C'est la partie qui distingue un usage sérieux d'un usage naïf. MapStruct a des défauts permissifs. Il faut les durcir.

La façon propre de les partager : un @MapperConfig.

@MapperConfig(
    componentModel = MappingConstants.ComponentModel.SPRING,
    injectionStrategy = InjectionStrategy.CONSTRUCTOR,
    unmappedTargetPolicy = ReportingPolicy.ERROR,
    nullValueCheckStrategy = NullValueCheckStrategy.ALWAYS
)
public interface CentralMapperConfig {}

@Mapper(config = CentralMapperConfig.class)   // ✓ hérite tout, peut surcharger
public interface OrderMapper { ... }

8Intégration Spring

Avec componentModel = "spring", MapperImpl est annoté @Component. On l'injecte comme n'importe quel bean.

@Service
@RequiredArgsConstructor
public class OrderService {
    private final OrderMapper orderMapper;   // ✓ injection de OrderMapperImpl
    private final OrderRepository orderRepository;

    public OrderDto get(Long id) {
        return orderRepository.findById(id)
            .map(orderMapper::toDto)
            .orElseThrow();
    }
}

Les mappers déclarés dans uses sont injectés aussi. Un mapper peut donc dépendre d'un autre, ou d'un Repository pour résoudre un id en entité (à utiliser avec parcimonie, cela cache des accès base dans un mapper).

En test unitaire, sans contexte Spring, Mappers.getMapper(OrderMapper.class) ne fonctionne pas avec le component model Spring. Deux options : instancier new OrderMapperImpl() directement, ou utiliser @SpringBootTest restreint avec @Import(OrderMapperImpl.class).

MapStruct Spring Extensions (projet séparé, version 2.0.0, Java 17 et Spring 6 minimum) va plus loin. Il génère des Converter<S, T> Spring et un ConversionService agrégé, pour appeler conversionService.convert(order, OrderDto.class) sans connaître le mapper. Utile dans un gros projet, superflu ailleurs.

9Pièges en production

Autres points à connaître :

• Getters "calculés" : une méthode getFullName() sans champ derrière est vue comme une propriété source. Elle peut créer un mapping non voulu.
• Ambiguïté de méthodes : deux méthodes default avec la même signature de types font échouer le build avec Ambiguous mapping methods found. Résolution avec @Named ou @Qualifier custom.
• Génération dans l'IDE : IntelliJ doit avoir l'annotation processing activé, sinon les Impl n'apparaissent pas et les tests échouent avec ClassNotFoundException.
• Tester le mapper : un test unitaire par mapper, avec new XxxMapperImpl(), sur un objet source complet. Cela documente le contrat et casse quand une règle change.

10Ce que MapStruct 1.7 apporte (beta)

La 1.7 est en beta (1.7.0.Beta2, juin 2026). Nouveautés notables :

• Optional natif : Optional<String> en source est déballé, en cible est enveloppé, sans méthode custom.
• JSpecify : les annotations @Nullable / @NonNull JSpecify sont respectées dans le code généré.
• Ignorer plusieurs cibles d'un coup : @Mapping(target = ..., ignore = true) répété est remplaçable par une seule annotation listant les champs.
• Sequenced Collections Java 21 et meilleur support Kotlin.
• Code généré modernisé : switch expressions pour les enums, diamant, multi-catch.

Pour un projet existant, rester en 1.6.3 jusqu'à la 1.7.0.Final. Les betas sont stables mais l'API peut bouger.

11Tableau de synthèse : quelle approche pour le mapping

Quand choisir :

• Manuel : 2 ou 3 DTO dans tout le projet, ou mapping avec beaucoup de logique métier.
• MapStruct : tout projet avec une couche DTO réelle. C'est le défaut raisonnable.
• Réflexion : à éviter sur du code neuf. Acceptable pour un prototype jetable.

Sources

• MapStruct Reference Guide (1.6.3) — documentation officielle complète : annotations, stratégies, component models, presence checks, héritage de configuration, décorateurs, mapping vers la cible courante (target = ".")
• MapStruct 1.7.0.Beta2 release notes — JSpecify, accessibilité configurable, code généré modernisé
• MapStruct 1.7.0.Beta1 release notes — Optional natif, Kotlin, Sequenced Collections, ignore multiple
• MapStruct Spring Extensions (GitHub) — génération de Converter et ConversionService Spring, 2.0.0 en Java 17 / Spring 6
• MapStruct examples (GitHub) — dont mapstruct-mapping-with-cycles pour le CycleAvoidingMappingContext, mapstruct-lombok pour le binding, mapstruct-decorator, mapstruct-object-factory et mapstruct-nested-bean-mappings