ModelMapper Java 完全指南：自动对象映射实战教程

1. 什么是 ModelMapper？为什么需要它？

ModelMapper 是一个强大的 Java 库，专门用于自动将一个类型的对象转换为另一个类型的对象（即对象映射）。在现代开发中，尤其是在使用分层架构（Controller → Service → Repository）时，开发者经常需要在 DTO（数据传输对象）、Entity（数据库实体）、VO（值对象）以及其他 POJO 之间复制数据。手动编写这类代码不仅繁琐、容易出错，还会导致代码臃肿、可读性下降。

ModelMapper 的核心目标是让开发者摆脱编写 source.getField() → target.setField() 这类样板代码。该库会分析类的结构（字段、getter/setter），并利用命名约定（约定优于配置）自动匹配它们。它支持嵌套对象、集合、继承以及复杂的转换，使其成为 Java 企业级应用中不可或缺的工具。

ModelMapper 在以下场景中尤其有用：

• 应用分层： 将 Entity 转换为 DTO，或反向转换，以便通过 REST API 传输数据。
• 微服务： 在不同服务的对象之间进行映射。
• 重构： 当类结构发生变化时，只需修改一个地方的映射配置。
• 测试： 基于现有对象快速创建测试数据。

2. 安装指南

ModelMapper 通过 Maven Central 分发。要安装它，需要在 pom.xml（Maven）或 build.gradle（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'

注意：版本 3.2.0 在本文撰写时是最新的。建议在 MVNRepository 上查看最新版本。

3. 快速入门——最小工作示例

来看一个最简单的例子：我们有一个 UserEntity 类（数据库实体）和一个 UserDTO 类（数据传输对象）。

// 源类 (Entity)
public class UserEntity {
    private Long id;
    private String firstName;
    private String lastName;
    private String email;

    // 构造函数、getter 和 setter
    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; }
}

// 目标类 (DTO)
public class UserDTO {
    private Long id;
    private String fullName; // 注意：字段名称不同
    private String emailAddress;

    // 构造函数、getter 和 setter
    public UserDTO() {}
    public Long getId() { return id; }
    public void