ModelMapper para Java: Guia Completo de Mapeamento Automático de Objetos

1. O que é ModelMapper e por que usá-lo?

ModelMapper é uma biblioteca poderosa para Java, projetada para converter (mapear) automaticamente objetos de um tipo em objetos de outro tipo. No desenvolvimento moderno, especialmente com arquiteturas em camadas (Controller → Service → Repository), os desenvolvedores frequentemente precisam copiar dados entre DTOs (Data Transfer Objects), Entities (entidades de banco de dados), VOs (Value Objects) e outros POJOs. Escrever esse código manualmente é tedioso, propenso a erros e resulta em código inchado e difícil de manter.

O principal objetivo do ModelMapper é eliminar a necessidade de escrever código repetitivo como source.getField() → target.setField(). A biblioteca analisa a estrutura das classes (campos, getters/setters) e as associa automaticamente, seguindo convenções de nomenclatura (convention over configuration). Ela suporta objetos aninhados, coleções, herança e transformações complexas, tornando-se uma ferramenta indispensável em aplicações corporativas Java.

O ModelMapper é especialmente útil nos seguintes cenários:

• Camadas da aplicação: Converter Entity em DTO e vice-versa para transferir dados via REST API.
• Microsserviços: Mapear objetos entre diferentes serviços.
• Refatoração: Quando a estrutura das classes muda, basta ajustar o mapeamento em um único local.
• Testes: Criar rapidamente dados de teste com base em objetos existentes.

2. Instalação

O ModelMapper é distribuído via Maven Central. Para instalá-lo, adicione a dependência ao arquivo pom.xml (para Maven) ou build.gradle (para Gradle).

Maven (pom.xml):

<dependency>
    <groupId>org.modelmapper</groupId>
    <artifactId>modelmapper</artifactId>
    <version>3.2.0</version>
</dependency>

Gradle (build.gradle):

implementation 'org.modelmapper:modelmapper:3.2.0'

Nota: A versão 3.2.0 é a mais recente no momento da escrita. Recomenda-se verificar a versão mais atual no MVNRepository.

3. Início rápido — exemplo mínimo funcional

Vamos a um exemplo simples: temos a classe UserEntity (entidade de banco de dados) e UserDTO (objeto para transferência de dados).

// Classe de origem (Entity)
public class UserEntity {
    private Long id;
    private String firstName;
    private String lastName;
    private String email;

    // Construtores, getters e setters
    public UserEntity() {}
    public UserEntity(Long id, String firstName, String lastName, String email) {
        this.id = id;
        this.firstName = firstName;
        this.lastName = lastName;
        this.email = email;
    }

    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    public String getFirstName() { return firstName; }
    public void setFirstName(String firstName) { this.firstName = firstName; }
    public String getLastName() { return lastName; }
    public void setLastName(String lastName) { this.lastName = lastName; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
}

// Classe de destino (DTO)
public class UserDTO {
    private Long id;
    private String fullName; // Observe: o campo tem nome diferente
    private String emailAddress;

    // Construtores, getters e setters
    public UserDTO() {}
    public Long getId() { return id; }
    public void