MapStruct in Quarkus

Prima di immergerci nel profondo, facciamo un rapido riepilogo su cosa sia MapStruct. È un generatore di codice che crea mapper di bean type-safe al momento della compilazione. Nessun sovraccarico a runtime, nessuna magia di riflessione - solo puro ed efficiente codice Java. Ecco un assaggio di come appare un mapper di base:

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);
    
    UserDTO mapToDTO(User user);
}

Semplice, vero? Ma oh, siamo solo all'inizio!

I 10 Trucchi di MapStruct che Non Sapevi di Avere Bisogno

1. Mappatura con Contesto: L'Ingrediente Segreto

Hai mai avuto bisogno di passare informazioni extra al tuo mapper? Ecco l'annotazione @Context:

@Mapper
public interface UserMapper {
    @Mapping(target = "role", source = "user")
    UserDTO mapToDTO(User user, @Context SecurityContext securityContext);
    
    default String mapRole(User user, @Context SecurityContext securityContext) {
        return securityContext.isAdmin() ? "ADMIN" : user.getRole();
    }
}

Ora puoi iniettare il contesto di runtime nella tua logica di mappatura. Fantastico, vero?

2. Mappature Personalizzate: Quando lo Standard Non Basta

A volte, devi rimboccarti le maniche e scrivere logica di mappatura personalizzata:

@Mapper
public interface DateMapper {
    @Mapping(target = "formattedDate", source = "date", qualifiedByName = "formatDate")
    DateDTO map(DateEntity date);
    
    @Named("formatDate")
    default String formatDate(LocalDate date) {
        return date != null ? date.format(DateTimeFormatter.ISO_LOCAL_DATE) : null;
    }
}

Consiglio: Usa @Named per mantenere i tuoi metodi personalizzati organizzati e riutilizzabili tra diversi mapper.

3. Mappatura di Collezioni: Perché Uno Non Basta Mai

MapStruct gestisce le collezioni come un campione:

@Mapper
public interface ProductMapper {
    List mapToDTOList(List products);
    
    Set mapToProductNames(List products);
}

Applica automaticamente la mappatura degli elementi a ogni elemento nella collezione. Magia!

4. Mappatura di Oggetti Annidati: Immersione Profonda

Gestire grafi di oggetti complessi? MapStruct ti copre le spalle:

@Mapper
public interface OrderMapper {
    @Mapping(target = "customerName", source = "customer.name")
    @Mapping(target = "orderItems", source = "items")
    OrderDTO mapToDTO(Order order);
    
    @Mapping(target = "productName", source = "product.name")
    OrderItemDTO mapToItemDTO(OrderItem item);
}

Gestisce senza problemi oggetti annidati, risparmiandoti dall'incubo della mappatura manuale.

5. Mappatura Condizionale: L'Arte del Prendere Decisioni

A volte, devi prendere decisioni di mappatura al volo:

@Mapper
public interface UserMapper {
    @Mapping(target = "status", expression = "java(mapStatus(user))")
    UserDTO mapToDTO(User user);
    
    default String mapStatus(User user) {
        return user.getLastLoginDate() != null && 
               user.getLastLoginDate().isAfter(LocalDate.now().minusDays(30)) 
               ? "ACTIVE" : "INACTIVE";
    }
}

Usa espressioni per iniettare logica complessa nelle tue mappature.

6. Ignorare Campi: L'Arte della Mappatura Selettiva

A volte, meno è meglio. Ignora i campi di cui non hai bisogno:

@Mapper
public interface UserMapper {
    @Mapping(target = "password", ignore = true)
    @Mapping(target = "createdAt", ignore = true)
    UserDTO mapToDTO(User user);
}

Perfetto quando gestisci dati sensibili o campi che non appartengono al tuo DTO.

7. Mappatura Inversa: Andare in Entrambe le Direzioni

Hai bisogno di mappare avanti e indietro? MapStruct ti copre:

@Mapper
public interface UserMapper {
    @Mapping(target = "id", ignore = true)
    User mapToEntity(UserDTO dto);
    
    UserDTO mapToDTO(User user);
}

Definisci semplicemente entrambi i metodi, e MapStruct gestirà la mappatura bidirezionale per te.

8. Valori Predefiniti: Riempire i Vuoti

A volte, devi fornire valori predefiniti per dati mancanti:

@Mapper
public interface ProductMapper {
    @Mapping(target = "inStock", constant = "true")
    @Mapping(target = "category", defaultValue = "UNCATEGORIZED")
    ProductDTO mapToDTO(Product product);
}

Usa constant per valori hardcoded e defaultValue per fallback quando la sorgente è nulla.

9. Prima e Dopo la Mappatura: Il Tocco Finale

Hai bisogno di eseguire alcune operazioni prima o dopo la mappatura? Ecco @BeforeMapping e @AfterMapping:

@Mapper
public abstract class OrderMapper {
    @Mapping(target = "total", ignore = true)
    public abstract OrderDTO mapToDTO(Order order);
    
    @AfterMapping
    protected void calculateTotal(Order order, @MappingTarget OrderDTO orderDTO) {
        orderDTO.setTotal(order.getItems().stream()
                               .mapToDouble(item -> item.getPrice() * item.getQuantity())
                               .sum());
    }
}

Perfetto per calcoli complessi o aggiustamenti dell'ultimo minuto.

10. Annotazioni Personalizzate di MapStruct: Il Potere dell'Astrazione

Crea le tue annotazioni per incapsulare modelli di mappatura comuni:

@Retention(RetentionPolicy.CLASS)
@Mapping(target = "id", ignore = true)
@Mapping(target = "createdAt", expression = "java(java.time.LocalDateTime.now())")
public @interface ToEntity { }

@Mapper
public interface UserMapper {
    @ToEntity
    User mapToEntity(UserDTO dto);
}

Questo approccio aiuta a mantenere i tuoi mapper puliti e promuove la riusabilità nel tuo codice.

Conclusione: La Magia di MapStruct Svelata

Ecco a te - 10 trucchi di MapStruct che porteranno il tuo gioco di mappatura con Quarkus al livello successivo. Dalle mappature consapevoli del contesto alle annotazioni personalizzate, MapStruct è ricco di funzionalità che possono semplificare anche le trasformazioni di oggetti più complesse.

Ricorda, la chiave per padroneggiare MapStruct è la sperimentazione. Non aver paura di immergerti nella documentazione e provare diverse combinazioni di queste tecniche. Il tuo futuro te stesso (e i tuoi revisori di codice) ti ringrazieranno per il codice di mappatura pulito, efficiente e manutenibile che produrrai.

Quindi, la prossima volta che ti trovi a raggiungere quella zuppa di setter manuali, fai un passo indietro e chiediti: "Cosa farebbe MapStruct?" È probabile che abbia un trucco nella manica che renderà la tua vita molto più facile.

Buona mappatura, ninja di Quarkus! 🚀

"L'arte della mappatura non è nel creare nuovi oggetti, ma nel rivelare le relazioni tra quelli esistenti." - Sviluppatore Anonimo (probabilmente)

P.S. Non dimenticare di mettere una stella al repository di MapStruct su GitHub se lo trovi utile. I progetti open source prosperano grazie al supporto della comunità!