MapStruct para Java: guia completo com exemplos

O que é MapStruct e para que serve?

MapStruct é um gerador de código para Java que cria automaticamente implementações de mapeadores (conversores) entre objetos de diferentes tipos. No desenvolvimento moderno em Java, surge frequentemente a necessidade de converter um objeto em outro: Entity em DTO, DTO em VO, uma resposta de API em outro modelo e assim por diante. Escrever esse código manualmente é um trabalho tedioso, demorado e propenso a erros. O MapStruct resolve esse problema gerando todo o código boilerplate em tempo de compilação.

Principais vantagens do MapStruct:

\n
• Desempenho: Geração de código em tempo de compilação (compile-time). Sem reflexão, sem perda de desempenho em tempo de execução. O MapStruct funciona tão rápido quanto se você escrevesse o mapeamento manualmente.
\n
• Segurança de tipos: Todos os erros (incompatibilidade de tipos, campos ausentes) são detectados em tempo de compilação, não em tempo de execução.
\n
• Simplicidade: Configuração mínima. Basta definir uma interface ou classe abstrata com métodos de mapeamento, e o MapStruct gera a implementação automaticamente.
\n
• Flexibilidade: Suporte a mapeamentos complexos, conversão de tipos, uso de expressões, chamada de métodos e integração com outras bibliotecas (Lombok, Spring, etc.).
\n
• Limpeza do código: O código de mapeamento é separado da lógica de negócios, tornando-o mais legível e sustentável.
\n

O MapStruct é especialmente útil em arquiteturas em camadas (Controller-Service-Repository), onde é frequentemente necessário converter objetos entre camadas.

Instalação do MapStruct

O MapStruct não é instalado via pip ou npm, pois é uma biblioteca para Java. Para adicionar o MapStruct ao seu projeto, utiliza-se o sistema de build Maven ou Gradle.

Instalação via Maven

Adicione as seguintes dependências ao seu arquivo pom.xml:

<dependencies>\n    <!-- Biblioteca principal do MapStruct -->\n    <dependency>\n        <groupId>org.mapstruct</groupId>\n        <artifactId>mapstruct</artifactId>\n        <version>1.5.5.Final</version>\n    </dependency>\n\n    <!-- Processador de anotações (para geração 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>

Instalação via Gradle

Para Gradle, adicione ao arquivo build.gradle:

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

Importante: Certifique-se de que a versão do mapstruct-processor corresponda à versão do mapstruct. Após adicionar as dependências, execute a compilação do projeto (por exemplo, mvn clean compile) para que o MapStruct gere as implementações dos mapeadores.

Início rápido com exemplo de código

Vamos criar um mapeador simples que converte o objeto Car (Entity) no objeto CarDto (DTO).

Passo 1: Defina as classes de origem e destino

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