源码仓库：mofan212/mapstruct-demo

0. 阅读前言

本文内容基于 MapStruct 官方文档进行翻译并拓展，力求保证文章准确性，但博主英语水平堪忧，在某些处理上仍有很多不足，还望各位看官不吝赐教。

翻译工作极其耗时，本文禁止转载！ 🙏

官网与推荐

MapStruct 官网：MapStruct

MapStruct 官方文档：Reference Guide

不错的 MapStruct 博客系列：属性映射工具——MapStruct（一）

1. MapStruct 概述

1.1 什么是 MapStruct

MapStruct 是一个 Java 注释处理器，用于生成类型安全的、高性能的、无依赖的 Bean 映射类。

在实际开发中经常会将各种对象相互转换，比如 DTO 转 BO，DTO 转 VO 等等，最简单的做法就是 new 对象，然后对属性值进行一个个地 GET/SET，但这样既繁琐又无聊。

如果有一个专门用来解决转换问题的工具就很棒了，MapStruct 就是这样的一个属性映射工具，只需要定义一个 Mapper 接口，MapStruct 就会自动实现这个映射接口，避免了复杂繁琐的映射实现。

补充与拓展

关于 Java 中的各种 O，可以参考下面这两篇文章：

java中各种O的含义(PO，DO，VO，TO，QO，BO，DAO，DTO，POJO)

浅析DTO、VO、DO、PO的概念

1.2 MapStruct 配置选项

MapStruct 代码生成器可以使用注释处理器选项进行配置。

在直接调用 javac 时，这些选项以 -Akey = value 的形式传递给编译器。通过 Maven 使用 MapStruct 时，任何处理器选项都可以在 Maven 处理器插件的配置中使用 compilerArgs 传递，如下所示：

12345678910111213141516171819202122232425262728293031...
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.5.1</version>
    <configuration>
        <source>1.8</source>
        <target>1.8</target>
        <annotationProcessorPaths>
            <path>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>${org.mapstruct.version}</version>
            </path>
        </annotationProcessorPaths>
        <!-- due to problem in maven-compiler-plugin, for verbose mode add showWarnings -->
        <showWarnings>true</showWarnings>
        <compilerArgs>
            <arg>
                -Amapstruct.suppressGeneratorTimestamp=true
            </arg>
            <arg>
                -Amapstruct.suppressGeneratorVersionInfoComment=true
            </arg>
            <arg>
                -Amapstruct.verbose=true
            </arg>
        </compilerArgs>
    </configuration>
</plugin>
...

关于存在的选项，可以参看官方文档 Configuration options，本文会在使用到的地方再具体讲解。

2. 定义映射器

2.1 Hello MapStruct

创建一个 Maven 项目，在 pom.xml 文件中添加以下配置：

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455<properties>
    <org.mapstruct.version>1.4.2.Final</org.mapstruct.version>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
</properties>

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

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <version>1.18.12</version>
        <scope>provided</scope>
    </dependency>

    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.13.1</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>1.8</source> <!-- depending on your project -->
                <target>1.8</target> <!-- depending on your project -->
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${org.mapstruct.version}</version>
                    </path>
                    <!--使用 Lombok 后，这里也要添加-->
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>1.18.12</version>
                    </path>
                    <!-- other annotation processors -->
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

注意： Maven 插件要使用 3.6.0 版本及以上、Lombok 使用 1.16.16 版本及以上。不然就会出现以下错误：

java: No property named "numberOfSeats" exists in source parameter(s). Did you mean "null"?

如果 Lombok 版本为 1.18.16 及以上，请再添加上：

12345<path>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok-mapstruct-binding</artifactId>
    <version>0.1.0</version>
</path>

创建一个 Car 实体类：

123456789101112/**
 * @author mofan 2021/2/2
 */
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class Car {
    private String make;
    private int numberOfSeats;
    private String type;
}

再创建一个 CarDto：

123456789101112/**
 * @author mofan 2021/2/2
 */
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class CarDto {
    private String make;
    private int seatCount;
    private String type;
}

还需要创建一个接口，用于对实体进行转换：

12345678910111213141516/**
 * @author mofan 2021/2/2
 */
@Mapper
public interface CarMapper {

    CarMapper INSTANCE = Mappers.getMapper(CarMapper.class);

    /**
     * 将 Car 转换成 CarDto
     * @param car Car 实例
     * @return    对应的 DTO
     */
    @Mapping(source = "numberOfSeats", target = "seatCount")
    CarDto carToCarDto(Car car);
}

最后创建测试类测试一下：

12345678910111213141516171819/**
 * @author mofan 2021/2/2
 */
public class CarMapperTest {
    @Test
    public void shouldMapCarToDto() {
        // given
        Car car = new Car( "Morris", 5,  "Sedan");

        // when
        CarDto carDto = CarMapper.INSTANCE.carToCarDto(car);

        // then
        assertNotNull(carDto);
        assertEquals("Morris", carDto.getMake());
        assertEquals(5, carDto.getSeatCount());
        assertEquals("Sedan", carDto.getType());
    }
}

运行测试方法，测试通过！🎉

为什么写一个接口后就能够帮我们实现实体的转换呢？

其实 Java 实体映射工具有两种：

1、在运行期，使用反射调用 Setter/Getter 方法或者是直接对成员变量赋值，这种方式通过 invoke() 执行赋值。一般会使用 Beanutil、Javassist 等开源库进行实现，代表产品有 Dozer 和 ModelMaper。

2、在编译期，动态生成含有逐一赋值的 class 文件，在运行时直接调用该 class 文件，这类的代表有 MapStruct、Selma、Orika。

如果不使用任何类库，手动实现实体的转换，可以使用反射（对应第一种方式），也可以对调用每个属性的 Get/Set 方法进行赋值（对应第二种方式）。

还是有点懵？

查看刚刚项目的 target 目录，可以看到：

自动生成了 CarMapperImpl 实现类，其内部仍然使用的是逐一复制的方式，只不过不用手动去写了。

正因如此，原实体和目标实体最好都编写各属性对应的 Getter 和 Setter 方法，以及它们各自的无参构造器。除此之外，别瞎使用 Lombok 中的 @Accessors 注解。

由于这个 class 文件是在编译期生成的，相比使用反射来实现实体映射，这种方式的效率更高。

更多 Bean 映射工具的性能对比，可以参考：5种常见Bean映射工具的性能比对

注意： 由于这些实现类会在编译期生成并存放在 target 目录中，因此当更改实体信息或映射逻辑时，需要重新编译或删除 target 目录再执行程序，否则更改可能不会生效。

注解介绍

在上述 Demo 中，使用到两个注解：

@Mapper：作用于接口上，告诉 MapStruct 需要编译期生成哪个接口的实现类。

在生成的实现类中，当原实体的属性与其目标实体对应的属性名称 相同 时，就直接被 隐式映射。如果名称不一样，就需要使用到 @Mapping 注解。

@Mapping：常作用于方法上，用于原实体与目标实体属性名称不相同时指定映射关系。

2.2 关闭隐式映射

MapStruct 存在默认的隐式映射，也可以关闭它，只需在接口对应的方法上添加注解：

1@BeanMapping(ignoreByDefault = true)

还是针对最开始的 Demo，在接口中的唯一方法上添加这个注解：

1234@BeanMapping(ignoreByDefault = true)
@Mapping(source = "numberOfSeats", target = "seatCount")
@Mapping(source = "make", target = "make")
CarDto carToCarDto(Car car);

在修改一下测试方法，查看打印结果：

12345678@Test
public void testBeanMapping() {
    Car car = new Car( "Morris", 5,  "Sedan");
    CarDto carDto = CarMapper.INSTANCE.carToCarDto(car);
    System.out.println(carDto.getMake());
    System.out.println(carDto.getSeatCount());
    System.out.println(carDto.getType());
}

Morris
5
null

由于没有使用 @Mapping 注解为 type 指定映射关系，因此 type 的属性值是 null。

但一般来说，没人会闲着没事把隐式映射关闭。🤨

2.3 @Mapping 注解

@Mapping 注解常作用于方法上，其实它也可以作用于注解之上，允许 @Mapping 用于其他（用户自定义的）注释以实现重用。

具体使用

新建 UserInfo 实体类：

123456789101112131415/**
 * @author mofan 2021/2/2
 */
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class UserInfo {
    private String id;
    private String username;
    private String pwd;
    private String dept;
    private Integer age;
    private Date createTime;
}

再新建 StudentDto 类：

123456789101112131415/**
 * @author mofan 2021/2/2
 */
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class StudentDto {
    private String id;
    private String username;
    private String password;
    private String department;
    private String age;
    private Date createTime;
}

要实现 UserInfo 向 StudentDto 转换。

再创建一个 FromUserInfo 注解，在这个注解之上使用 @Mapping 注解：

123456789/**
 * @author mofan 2021/2/2
 */
@Retention(RetentionPolicy.CLASS)
@Mapping(target = "id", ignore = true)
@Mapping(target = "createTime", expression = "java(new java.util.Date())")
@Mapping(source = "dept", target = "department")
public @interface FromUserInfo {
}

创建 UserInfoMapper 接口：

1234567891011121314151617/**
 * @author mofan 2021/2/2
 */
@Mapper
public interface UserInfoMapper {

    UserInfoMapper INSTANCE = Mappers.getMapper(UserInfoMapper.class);

    /**
     * 转换为 StudentDto
     * @param userInfo userInfo
     * @return StudentDto 实例
     */
    @FromUserInfo
    @Mapping(source = "pwd", target = "password")
    StudentDto toStudent(UserInfo userInfo);
}

最后来个测试类测试一下：

1234567891011121314151617181920/**
 * @author mofan 2021/2/2
 */
public class UserInfoMapperTest {

    @Test
    public void testToStudent() {
        UserInfo userInfo = new UserInfo("1", "mofan", "123456",
                // 2020-11-02 21:54:29
                "开发部", 19, new Date(1604325269401L));
        StudentDto studentDto = UserInfoMapper.INSTANCE.toStudent(userInfo);

        System.out.println(studentDto.getId());
        System.out.println(studentDto.getUsername());
        System.out.println(studentDto.getPassword());
        System.out.println(studentDto.getDepartment());
        System.out.println(studentDto.getAge());
        System.out.println(studentDto.getCreateTime());
    }
}

运行测试类后，控制台输出：

null
mofan
123456
开发部
19
Tue Feb 02 18:33:11 CST 2021

@Mapping 属性讲解

上述案例中又使用了 @Mapping 注解的两个属性：ignore 和 expression。

在实体转换时，如果不想让某个属性值从源实体赋值到新实体，可以使用 @Mapping 注解的 target 指定新实体中不想被赋值的属性，同时将 ignore 设置为 true。

expression 的含义就是表达式，使用这个属性，可以为新实体中某个属性指定成表达式设置的值。表达式格式为：java(<EXPRESSION>)，其实就是一句 Java 代码。比如想让 username 字段设置为 默烦，可以这些写：

1@Mapping(target = "username", expression = "java(\"默烦\")")

需要注意的是： source 属性和 expression 属性不能同时存在。使用 expression 时，其值的 Java 代码所使用的类最好使用全类名，但如果这个 Java 代码会抛异常就不要使用 expression 了，而是需要自定义方法并在 qualifyByName 中引用。

像上述案例中，createTime 的值是指 2020-11-02 21:54:29，为其指定表达式后，原本的值发生了改变。

如果仔细观察，还能发现 MapStruct 会对数据进行自动转换。比如在原实体中的 age 属性是 Integer 类型的，而 目标实体中的 age 属性是 String 类型的，即便如此，仍然能够映射成功。👍

@Mapping 其他属性

@Mapping 注解还有其他的属性：

1. dateFormat：原属性是 Date，转化为 String
2. numberFormat：数值类型与 String 类型之间的转化
3. constant：不管源属性值，直接将目标属性设置为指定的常量
4. qualifiedByName：根据自定义的方法进行赋值
5. defaultValue：默认值。如果原属性值为 null，那么设置目标属性值为指定的默认值

这种方式有什么用？

如果有若干个 DTO 都由同一实体转换而来，这些 DTO 有些属性名称是相同的，但有些又不一样，那么我们就可以编写一个注解，在这个注解上使用 @Mapping 注解，以减少重复代码。

使用 @Mapping 注解作用与其他注解上并使用其他注解时，可以让若干个 DTO 都具备相同的特性。在官网上称这种观点为 「duck-typing」（鸭子类型），当一个东西叫声像鸭子，走路像鸭子，还会游泳，那么它很有可能就是鸭子 🦆。简单来说就是特性决定了类型，而不是类型决定了特性。鸭子类型在动态语言中经常使用，比如 Python，这使得 Python 不像 Java 那样专门去弄一大堆的设计模式。🤪

好了，说远了，回到 MapStruct 上。

但是官网又说，这个功能尚不成熟，用户应当谨慎使用，尤其是在不确定何时始终存在属性时：

the method on which the problem occurs is displayed, as well as the concerned values in the @Mapping annotation. However, the composition aspect is not visible.

2.4 默认方法与抽象类

在 JDK 8 及其更高的版本中，接口中也可以有方法的实现，但是这些方法必须被 static 或 default 关键词修饰。

使用 MapStruct 可以实现简单类型的映射，但是没办法完成一些带有逻辑的映射。比如在原实体中有一个名为 age 的属性，在映射到新实体时，想让 age 的值加一，这对于 MapStruct 来说是无法做到的。

此时可以在接口中定义默认方法，只要参数是原实体类型，返回值是新实体类型，那么使用 MapStruct 生成接口的实现类时将调用这个默认方法。

除此之外，还可以使用抽象类来定义映射器，而不仅仅是接口。 在这种情况下，MapStruct 会生成抽象类的子类，并实现所有的抽象方法。而对于非抽象方法来说，只要参数和返回值类型匹配，MapStruct 也会子类中调用这些方法。与声明默认方法相比，使用抽象类来定义映射器可以在映射器类中声明额外的字段。

2.5 多个源参数

MapStruct 支持带有多个源参数的映射方法。 比如，可以将实体 A 中的部分属性值和实体 B 中的部分属性值映射到同一 DTO 中：

123456@Mapper
public interface AddressMapper {
    @Mapping(source = "person.description", target = "description")
    @Mapping(source = "address.houseNo", target = "houseNumber")
    DeliveryAddressDto personAndAddressToDeliveryAddressDto(Person person, Address address);
}

与单参数映射方法一样，属性是按名称映射的。

如果多个源参数中定义了具有相同名称的属性，那么必须使用 @Mapping 注释来指定要从哪个源参数中的同名属性映射到目标实体，否则就会报错。对于仅在给定源参数中出现一次的属性，由于 隐式映射 的关系，因此可以选择性地指定名称。

注意： 具有多个源参数的映射方法将在 所有 源参数为空的情况下才返回 null。否则，目标实体将被实例化，同时将所有来自所提供参数的属性值映射到目标实体中。

MapStruct 还支持直接引用源参数。 比如源参数中有一个 Integer 类型的参数，可以直接将这个参数映射到目标实体中：

123456@Mapper
public interface AddressMapper {
    @Mapping(source = "person.description", target = "description")
    @Mapping(source = "hn", target = "houseNumber")
    DeliveryAddressDto personAndAddressToDeliveryAddressDto(Person person, Integer hn);
}

2.6 多个嵌套属性映射

如果在实体 A 中存在某一属性 B，其类型是一个实体，现在想将实体 A 中的 B 对象映射到某一不含任何复杂对象类型属性的 DTO 中，那么需要取出属性 B 的各个属性进行一一映射。

如果实体 A 存在多个复杂对象类型的属性，依次进行映射会十分繁琐。

MapStruct 支持使用 . 作为 @Mapping 注释中 target 的属性值。这告诉 MapStruct 将原实体中所有复杂对象类型的属性中的所有属性映射到目标实体。

1234567@Mapper
public interface CustomerMapper {
    @Mapping(target = "name", source = "record.name")
    @Mapping(target = ".", source = "record")
    @Mapping(target = ".", source = "account")
    Customer customerDtoToCustomer(CustomerDto customerDto);
}

上述代码将 customerDto 对象中的 record 对象和 account 对象的各个属性都映射到目标实体中，但由于 record 和 account 都有 name 属性，因此需要显式指定以消除歧义。

2.7 更新存在的实例

在某些情况下，可能并不需要创建一个新的目标实体，而是更新一个现有的实例，这个时候就需要用到 @MappingTarget 注解。

简单来说：一个原实体 A 的属性数量比目标实体 B 少，因此将 A 映射为 B 时，B 中有些属性值会是空。B 中的这些属性是存在于实体 C 中的，那么可以使用 C 来更新 B。

具体使用

原实体 UserInfo：

123456789101112@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class UserInfo {
    private String id;
    private String username;
    private String pwd;
    private String dept;
    private Integer age;
    private Date createTime;
}

目标对象 TeacherDto：

12345678910111213141516171819/**
 * @author mofan 2021/2/3
 */
@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
public class TeacherDto {
    private String id;
    private String username;
    private String password;
    private String department;
    private String age;
    private Date createTime;
    private String firstName;
    private String lastName;
    private Integer sex;
    private String idCardNum;
}

另一实体 PersonInfo：

12345678910111213/**
 * @author mofan 2021/2/3
 */
@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
public class PersonInfo {
    private String firstName;
    private String lastName;
    private Integer gender;
    private String idCardNum;
}

转换接口中的方法：

123456789101112131415161718/**
 * 转换为 TeacherDto --> 缺少部分属性值
 *
 * @param userInfo userInfo
 * @return TeacherDto 实例
 */
@Mapping(source = "pwd", target = "password")
@Mapping(source = "dept", target = "department")
TeacherDto toTeacherDto(UserInfo userInfo);

/**
 * 更新 TeacherDto 实例 --> 补充缺少的属性值
 *
 * @param personInfo personInfo
 * @param teacherDto teacherDto
 */
@Mapping(source = "gender", target = "sex")
void updateTeacherDto(PersonInfo personInfo, @MappingTarget TeacherDto teacherDto);

测试方法：

123456789101112131415161718@Test
public void testToTeacherDto() {
    UserInfo userInfo = new UserInfo("1", "mofan", "123456",
            // 2020-11-02 21:54:29
            "开发部", 19, new Date(1604325269401L));
    TeacherDto teacherDto = UserInfoMapper.INSTANCE.toTeacherDto(userInfo);
    assertEquals("123456", teacherDto.getPassword());
    assertNull(teacherDto.getFirstName());

    PersonInfo personInfo = new PersonInfo();
    personInfo.setFirstName("默");
    personInfo.setLastName("烦");
    personInfo.setGender(1);
    personInfo.setIdCardNum("123456788914725896");
    UserInfoMapper.INSTANCE.updateTeacherDto(personInfo, teacherDto);
    assertEquals("默", teacherDto.getFirstName());
    assertEquals(1, teacherDto.getSex().intValue());
}

在更新实例时，如果存在字段名不一样的情况，仍然可以使用 @Mapping 注解进行指定。

在更新对象的方法中，除了使用 void 作为返回值外，还可以使用目标参数类型作为返回值，这表示在更新目标参数后又返回它。比如：

12@Mapping(source = "gender", target = "sex")
TeacherDto updateTeacherDto(PersonInfo personInfo, @MappingTarget TeacherDto teacherDto);

2.8 反向映射

上述实例中，都是用实体转换为 DTO，那么怎么将 DTO 转换回实体呢？

当然可以使用 @Mapping 注解一一指定，但这样也太麻烦了，有没有什么简单的方法呢？

MapStruct 提供了一个名为 @InheritInverseConfiguration 的注解用于反向映射。该注解只有一个属性 name，表示原映射名，即原映射方法名。

具体使用

新实体 PeopleInfo：

12345678910111213141516/**
 * @author mofan 2021/2/3
 */
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class PeopleInfo {
    private Long id;
    private String name;
    private String age;
    private Date createTime;
    private Double weight;
    private String bloodType;
    private GenderEnum gender;
}

打工人 WorkerDto：

12345678910111213141516/**
 * @author mofan 2021/2/3
 */
@Setter
@Getter
@NoArgsConstructor
@AllArgsConstructor
public class WorkerDto {
    private Long id;
    private String name;
    private Integer age;
    private String createTime;
    private String weight;
    private String bloodType;
    private Integer gender;
}

一个用于转换实体的接口 PeopleInfoMapper：

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667/**
 * @author mofan 2021/2/3
 */
@Mapper
public interface PeopleInfoMapper {
    PeopleInfoMapper INSTANCE = Mappers.getMapper(PeopleInfoMapper.class);

    /**
     * 将 PeopleInfo 转换为 WorkerDto
     *
     * @param peopleInfo peopleInfo实例
     * @return WorkerDto
     */
    @Mappings({
            @Mapping(target = "name", defaultValue = "默烦"),
            @Mapping(target = "age", expression = "java(java.lang.Integer.valueOf(peopleInfo.getAge()) + 1)"),
            @Mapping(target = "createTime", dateFormat = "yyyy-MM-dd"),
            @Mapping(target = "weight", numberFormat = "0.00"),
            @Mapping(target = "bloodType", constant = "A 型血"),
            @Mapping(source = "gender", target = "gender", qualifiedByName = "getGenderEnumCode")
    })
    WorkerDto toWorkerDto(PeopleInfo peopleInfo);

    /**
     * 将 DTO 转换为实体
     *
     * @param workerDto workerDto 实例
     * @return PeopleInfo
     */
    @InheritInverseConfiguration(name = "toWorkerDto")
    @Mappings({
            @Mapping(target = "age", expression = "java(java.lang.String.valueOf(workerDto.getAge()))"),
            @Mapping(target = "bloodType", constant = "B 型血"),
            @Mapping(target = "gender", qualifiedByName = "getGenderEnum")
    })
    PeopleInfo fromPersonInfo(WorkerDto workerDto);

    /**
     * 根据枚举值的代码获取枚举值
     *
     * @param code 枚举值对应的代码
     * @return 枚举值
     */
    @Named("getGenderEnum")
    default GenderEnum getGenderEnum(Integer code) {
        for (GenderEnum value : GenderEnum.values()) {
            if (value.getCode().equals(code)) {
                return value;
            }
        }
        return null;
    }

    /**
     * 根据性别枚举值获取对应的代码
     *
     * @param genderEnum 枚举值
     * @return 枚举值对应的代码
     */
    @Named("getGenderEnumCode")
    default Integer getGenderEnumCode(GenderEnum genderEnum) {
        if (genderEnum == null) {
            return null;
        }
        return genderEnum.getCode();
    }
}

编写一手测试方法：😎

1234567891011121314151617181920212223242526@Test
public void testInheritInverseConfiguration() {
    PeopleInfo peopleInfo = new PeopleInfo();
    peopleInfo.setId(233L);
    // 缺少 name 属性值
    peopleInfo.setAge("18");
    peopleInfo.setCreateTime(new Date(1604325269401L));
    peopleInfo.setWeight(122.2345);
    peopleInfo.setBloodType("AB 型血");
    peopleInfo.setGender(GenderEnum.MAN);

    // to workerDto
    WorkerDto workerDto = PeopleInfoMapper.INSTANCE.toWorkerDto(peopleInfo);
    assertEquals("默烦", workerDto.getName());
    assertEquals(1, workerDto.getGender().intValue());
    assertEquals(19, workerDto.getAge().intValue());
    System.out.println(workerDto.getCreateTime());
    System.out.println(workerDto.getWeight());
    System.out.println(workerDto.getBloodType());

    // from PeopleInfo
    PeopleInfo person = PeopleInfoMapper.INSTANCE.fromPersonInfo(workerDto);
    assertEquals("B 型血", person.getBloodType());
    assertEquals("19", person.getAge());
    assertEquals(GenderEnum.MAN, person.getGender());
}

运行测试方法后，测试通过，控制台打印：

2020-11-02
122.23
A 型血

总结

由于 age 的转化中使用了 expression、bloodType 转化的过程中使用了 constant，这两个属性对应的 @Mapping 注释都没有指定 source。所以在使用 @InheritInverseConfiguration 注解进行反向映射时，需要使用 @Mapping 对这两个属性进行单独的映射，不然就会报错。

在 PeopleInfo 中 gender 属性类型是 GenderEnum 枚举类型，而 WorkerDto 中的 gender 属性是 Integer 类型的，因此在进行属性映射时，需要指定映射方式，这里涉及到 @Named 注解和 @Mapping 注解中 qualifiedByName 属性的使用。

2.9 直接使用字段映射

在前面的案例中，实现与实体之间的映射时都需要实体中有 Getter 和 Setter 方法，但 MapStruct 也支持没有 Getter 和 Setter 的公共字段映射。如果 MapStruct 为属性找不到合适的 Getter 和 Setter 方法，它会把字段作为读 / 写访问器。

如果一个字段被 public 或 public final 修饰，那么它会被认为是一个读访问器。如果一个字段被 static 修饰，它不会被认为是一个读访问器。

当一个字段 仅仅只 被 public 修饰时，它才会被认为是一个写访问器。如果一个字段被 final 或 static 修饰，它不会被认为是一个写访问器。

比如，这样两个实体是能够被相互映射的：

1234567891011121314@Setter
@Getter
@NoArgsConstructor
@AllArgsConstructor
public class Customer {
    private Long id;
    private String name;
}

public class CustomerDto {
    // 注意这些字段是被 public 修饰的
    public Long id;
    public String customerName;
}

由于 name 属性和 customerName 属性名称不一样，在进行映射时，需要使用 @Mapping 指定规则。

2.10 使用构建器

在 MapStruct 中，支持通过构建器对不可变类型进行映射。

当进行映射时，MapStruct 会检查被映射的类中是否有构建器。这是通过 BuilderProvider 完成的，如果这个类存在构建器，那么该构建器将被用于映射。

BuilderProvider 的默认实现假设如下：

• 该类型拥有返回 Builder 对象的公共无参静态方法（该方法称为 构建器创建方法）。比如 Person 类中有一个公共静态方法，它返回 PersonBuilder

• Builder 类型有一个公共无参方法（该方法称为 构建方法），它返回正在构建的对象类型。比如 PersonBuilder 中有一个 build() 方法，该方法的返回值类型是 Person

• 在有多个 构建方法 的情况下，MapStruct 会寻找一个叫做 build() 的方法，如果存在这样的方法，将使用这个方法，否则编译错误

• 可以在 @BeanMapping、@Mapper 或 @MapperConfig 等注解中使用 @Builder 来定义特定的 构建方法

• 如果有多个 构建器创建方法 满足上述条件，DefaultBuilderProvider 会抛出 MoreThanOneBuilderCreationMethodException 异常。如果发生 MoreThanOneBuilderCreationMethodException，MapStruct 将在编译期间写入警告，并且不使用任何生成器

如果在被映射的类中存在上述的方法和构建器，为了完成映射，MapStruct 会调用构建器的构建方法并生成代码。

还可以通过 MapStruct 的 @Builder 的 disableBuilder 属性来禁用构建器检测。MapStruct 将在构建器被禁用的情况下回到常规的 Getter / Setter 来生成代码。还可以在 Maven 处理器插件的配置中使用 <compilerArgs> 添加 <arg>-Amapstruct.disableBuilders=true</arg> 来禁用构建器的检测。

对象工厂也被认为是构建器。例如，如果 PersonBuilder 中存在一个对象工厂，MapStruct 将使用对象工厂而不是 构建器创建方法。

构建器的检测会影响 @BeforeMapping 和 @AfterMapping 注解的行为，这在后文会介绍。

具体使用

原实体 Animal：

1234567891011/**
 * @author mofan 2021/2/3
 */
@Setter
@Getter
@NoArgsConstructor
@AllArgsConstructor
public class Animal {
    private String name;
    private String type;
}

目标实体与构造器：

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647/**
 * @author mofan 2021/2/3
 */
@Getter
@Setter
public class DogDto {
    private String name;
    private final String type;

    protected DogDto (DogDto.Builder builder) {
        this.type = builder.type;
        this.name = builder.name;
    }

    /**
     * 构建器创建方法
     *
     * @return 构建器
     */
    public static DogDto.Builder builder() {
        return new DogDto.Builder();
    }

    public static class Builder {
        private String type;
        private String name;

        public Builder type (String type) {
            this.type = type;
            return this;
        }

        public Builder name(String name) {
            this.name = name;
            return this;
        }

        /**
         * 构建方法
         *
         * @return 被构建的对象
         */
        public DogDto create() {
            return new DogDto(this);
        }
    }
}

转换接口：

123456789101112131415/**
 * @author mofan 2021/2/3
 */
@Mapper
public interface AnimalMapper {

    AnimalMapper INSTANCE = Mappers.getMapper(AnimalMapper.class);

    /**
     * 将 Animal 转换为 DogDTO
     * @param animal Animal 实例
     * @return DogDto 实例
     */
    DogDto toDogDto(Animal animal);
}

测试方法：

123456789101112131415/**
 * @author mofan 2021/2/3
 */
public class AnimalMapperTest {
    @Test
    public void testToDogDto() {
        Animal animal = new Animal();
        animal.setName("小黑");
        animal.setType("dog");

        DogDto dogDto = AnimalMapper.INSTANCE.toDogDto(animal);
        assertEquals("小黑", dogDto.getName());
        assertEquals("dog", dogDto.getTYPE());
    }
}

运行测试方法后，测试通过。查看 target 目录，可以看到生成的代码如下：

123456789101112131415public class AnimalMapperImpl implements AnimalMapper {
    public AnimalMapperImpl() {
    }

    public DogDto toDogDto(Animal animal) {
        if (animal == null) {
            return null;
        } else {
            Builder dogDto = DogDto.builder();
            dogDto.type(animal.getType());
            dogDto.name(animal.getName());
            return dogDto.create();
        }
    }
}

总结

这其实使用了一种设计模式 —— 构建者模式，或者说建造者模式。

在《Effective Java》一书中有提到，一个类的构造函数参数个数有多个时，而且这些参数有些是可选的参数，要考虑使用构建器，即使用构建者模式。

但上述代码中并没有体现可选参数的概念，要想体现也很简单，只需要在构建器中编写编写一个构造方法，构造方法的参数就是需要必填的参数。

每次使用构建者模式都会书写许多样板代码，Lombok 提供了一个 @Builder 注解，使用这个注解可以很快地实现构建者模式。使用 @Builder 生成的构造方法是共有的，不符合构建者模式的思想，因此还需要指定构造方法的访问修饰符。比如指定成 protected：

1234567891011/**
 * @author mofan 2021/2/3
 */
@Getter
@Setter
@Builder
@AllArgsConstructor(access = AccessLevel.PROTECTED)
public class DogDto {
    private String name;
    private final String type;
}

将 DogDto 修改成以上形式后，运行测试方法也是可以通过的。:punch:

2.11 使用构造函数

在前文中，对象映射使用 Getter / Setter 完成。MapStruct 也支持使用构造方法来映射目标类型。

在进行映射时，MapStruct 会检查被映射的实体中是否存在构建器。如果没有构建器，MapStruct 会寻找一个可访问的构造方法。

构造方法的选择

当有多个构造函数时，MapStruct 按照以下优先级进行选择：

1. 被 @Default （该注解可以来自任何包！😲）注释所标注的公共构造方法（最高优先级）；
2. 如果 只有一个公共 的构造方法，那么它将被用于构造对象，而其他非公共的构造方法会被忽略；
3. 如果存在一个无参构造方法，那么它将被用于构造对象，而其他构造方法会被忽略；
4. 如果有多个符合条件的构造方法，会因为构造方法指代不清而造成编译错误。在这个时候，可以使用 @Default 注解来指定用于构造对象的构造方法。

官网给出的示例：

123456789101112131415161718192021222324public class Vehicle {
    protected Vehicle() { }
    // MapStruct will use this constructor, because it is a single public constructor
    public Vehicle(String color) { }
}

public class Car {
    // MapStruct will use this constructor, because it is a parameterless empty constructor
    public Car() { }
    public Car(String make, String color) { }
}

public class Truck {
    public Truck() { }
    // MapStruct will use this constructor, because it is annotated with @Default
    @Default
    public Truck(String make, String color) { }
}

public class Van {
    // There will be a compilation error when using this class because MapStruct cannot pick a constructor
    public Van(String make) { }
    public Van(String make, String color) { }
}

在使用构造方法时，将使用构造方法的参数名并与目标属性进行匹配。当构造函数被 @ConstructorProperties （该注解也可以来自任何包，只不过通常使用 java.beans.ConstructorProperties）标注时，该注解将被用来获取参数的名称。

当目标实体中存在对象工厂方法或用 @ObjectFactory 标记的方法时，这些方法将优于目标中任何构造方法。在这种情况下，目标实体中的构造方法不会被使用。

具体使用

自己编写的 @Default 注解：

1234567/**
 * @author mofan 2021/2/5
 */
@Target(ElementType.CONSTRUCTOR)
@Retention(RetentionPolicy.CLASS)
public @interface Default {
}

创建一个 Book 实体：

12345678910/**
 * @author mofan 2021/2/5
 */
@Setter
@Getter
public class Book {
    private String bookName;
    private Double price;
    private String author;
}

再创建一个 NovelDto，后续会将 Book 对象转换为 NovelDto：

123456789101112131415161718192021222324/**
 * @author mofan 2021/2/5
 */
@Getter
public class NovelDto {
    private final String bookName;
    private final Double price;
    private String author;

    @Default
    // @ConstructorProperties 注解指定来源对象的属性名
    @java.beans.ConstructorProperties({"bookName", "price", "author"})
    public NovelDto(String book, Double price, String author) {
        this.bookName = book;
        this.price = price;
        this.author = "author";
    }


    public NovelDto(String bookName, Double price) {
        this.bookName = bookName;
        this.price = price;
    }
}

一个用于实体映射的接口：

12345@Mapper
public interface BookMapper {
    BookMapper INSTANCE = Mappers.getMapper(BookMapper.class);
    NovelDto toNovelDto(Book book);
}

测试方法：

1234567891011@Test
public void testToNovel() {
    Book book = new Book();
    book.setBookName("Effective Java");
    book.setPrice(78.0);
    NovelDto novelDto = BookMapper.INSTANCE.toNovelDto(book);

    assertEquals("Effective Java", novelDto.getBookName());
    assertEquals("author", novelDto.getAuthor());
    assertEquals(78.0, novelDto.getPrice(), 0.0);
}

运行测试方法后，测试通过！

查看生成的代码：

1234567891011121314public NovelDto toNovelDto(Book book) {
    if (book == null) {
        return null;
    } else {
        String bookName = null;
        Double price = null;
        String author = null;
        bookName = book.getBookName();
        price = book.getPrice();
        author = book.getAuthor();
        NovelDto novelDto = new NovelDto(bookName, price, author);
        return novelDto;
    }
}

总结

通过生成代码来看，使用到了原目标实体的 Getter 方法，用到了目标实体的构造方法，因此在编码时需要保证存在这些方法 才能使用构造函数进行映射。

使用 MapStruct 将 Book 实体转换成 NovelDto 时，在 NovelDto 中没有 Setter 方法，但存在多个构造方法，最终会选取合适的构造方法进行映射。

在 NovelDto 实体类中存在两个构造方法，且都是公共有参构造方法，因此需要使用 @Default 进行指明要使用哪个构造方法进行映射，如果不指明就会在编译阶段报错。

但是在 MapStruct 中并没有提供 @Default 注解，那怎么办？🤔

根据官方文档 14.1. Non-shipped annotations 的说话，只要使用任意一个能够作用在构造方法且名为 @Default 的注解就行，也就是任意第三方的、能作用于构造方法上的 @Default 注解都能够被 MapStruct 识别，并将注解标记的构造方法作为映射的构造方法。那问题来了，在没有引入第三方依赖，且当前项目中没有符合条件的 @Default 注解咋办？

自己写一个就行，MapStruct 也能识别。具体参见上述提供的代码。😁

使用目标实体的构造方法时，会使用该构造方法的参数名并与 来源实体 的属性进行匹配。务必保证这些名称是一样的，否则无法映射成功。 当然，也不是说名称不一样就不能映射，这时候可以使用 @ConstructorProperties 注解，使用这个注解指定构造方法的第几个参数对应来源对象的哪个 Getter 方法，从而完成参数名与属性的匹配。

那如果目标实体的属性名和原实体的属性名不一致怎么办？这就需要用到前面说的 @Mapping 注解了。😏

备注： 这一块或许比较难理解，建议使用上述代码进行小改然后一一理解。😔

2.12 将 Map 映射到对象

在某些情况下，可能需要将 Map<String, Object> 映射到某个对象，MapStruct 也是支持这种需求的，此时 @Mapping 中的 source 属性值为 Map 中的 key（把 Map 当成一个没有特定类型的对象）。比如：

123456789101112@Setter
@Getter
public class Customer {
    private Long id;
    private String name;
}

@Mapper
public interface CustomerMapper {
    @Mapping(target = "name", source = "customerName")
    Customer toCustomer(Map<String, String> map);
}

生成的代码如下：

12345678910public class CustomerMapperImpl implements CustomerMapper {
    @Override
    public Customer toCustomer(Map<String, String> map) {
        // --snip--
        if ( map.containsKey( "customerName" ) ) {
            customer.setName( map.get( "customerName" ) );
        }
        // --snip--
    }
}

当使用 raw map（没有指定泛型的 Map） 或没有字符串作为键的 Map 时，将生成警告。如果 Map 本身直接映射到其他目标属性，则不会生成警告。

3. 获取映射器

3.1 映射器工厂

当没有使用依赖注入框架（比如 Spring）时，可以使用 org.mapstruct.factory.Mappers 类来获取一个映射器（Mapper）实例。

使用方法： 调用该类的 Mappers#getMapper() 方法，传入要返回的 Mapper 接口类型。

通常来说，习惯于将映射器实例命名为 INSTANCE。

在前文中，大部分都是使用接口来定义映射器，而在抽象类中应该这样定义映射器，比如：

12345@Mapper
public abstract class CarMapper {
    public static final CarMapper INSTANCE = Mappers.getMapper(CarMapper.class);
    CarDto carToCarDto(Car car);
}

这种模式使得客户端可以非常容易地使用映射器对象，而不需要重复实例化新的实例。

MapStruct 生成的映射器是无状态和线程安全的，在多线程环境下可以放心使用。

3.2 使用依赖注入

在实际项目中，一般都会使用依赖注入框架（比如：Spring），这个时候就需要通过依赖注入而不是通过 Mappers#getMapper() 来获取映射器对象。可以通过 @Mapper 的 componentModel 属性或使用配置选项中描述的 Configuration options 指定生成的映射器类应基于的组件模型。

目前，MapStruct 支持 CDI 和 Spring。在这两种情况下，所需的注解将被添加到生成的映射器实现类中，以便使其同样受到依赖注入的影响。

@Mapper#componentModel 属性或 mapstruct.defaultComponentModel 配置选项支持的值：

从 MapStruct 1.5.0.Final 开始，这些值在 org.mapstruct.MappingConstants.ComponentModel 类中以常量的形式存在。

当 mapstruct.defaultComponentModel 配置选项和 @Mapper#componentModel 同时指定了值，以 @Mapper 注解的为准。

使用其他映射器类的映射器将使用配置的组件模型获得这些映射器。比如，映射器 A 是一个 Spring Bean，映射器 A 中注入了映射器 B，那么映射器 B 也必须是一个可注入的 Spring Bean。

3.3 注入策略

使用依赖注入时，可以指定注入策略。

可以通过 @Mapper 和 @MapperConfig 注解的 injectionStrategy 属性或 mapstruct.defaultInjectionStrategy 来指定注入策略。注入策略有两种：构造方法和属性注入，默认是属性注入。

针对 @Mapper 的 injectionStrategy 属性来说，其值是一个枚举：

123456public enum InjectionStrategy {
    /** Annotations are written on the field **/
    FIELD,
    /** Annotations are written on the constructor **/
    CONSTRUCTOR
}

1. 使用属性注入时，依赖关系将被注入到字段中。
2. 使用构造函数注入时，将生成构造函数，依赖关系将通过构造函数注入。

如果 MapStruct 检测到 需要使用 @Mapper#uses 属性的实例进行映射，则生成的映射器将注入在 uses 属性中定义的类。注意 需要使用 几个字，如果参与映射字段不需要使用指定类型对应的实例进行映射，那么生成的映射器不会注入 uses 属性中定义的类。

对于抽象类或装饰器应使用属性注入，因为它们不能被实例化。

具体使用

使用最开始的 Car 和 CarDto 两个实体进行测试，省略实体代码。

导入 Spring 所需要的依赖：

123456789101112<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>5.2.7.RELEASE</version>
</dependency>

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-test</artifactId>
    <version>5.2.7.RELEASE</version>
    <scope>test</scope>
</dependency>

编写一个 SpringConfig 配置类，主要用于扫描包：

1234567/**
 * @author mofan 2021/2/6
 */
@Configuration
@ComponentScan("indi.mofan.mapper")
public class SpringConfig {
}

编写映射器，使用 Spring 的依赖注入：

123456789/**
 * @author mofan 2021/2/6
 */
@Mapper(componentModel = "spring")
public interface CarInjectMapper {

    @Mapping(source = "numberOfSeats", target = "seatCount")
    CarDto carToCarDto(Car car);
}

测试类与测试方法：

12345678910111213141516171819/**
 * @author mofan 2021/2/6
 */
@RunWith(SpringRunner.class)
@ContextConfiguration(classes = SpringConfig.class)
public class DependencyInjectionTest {

    @Autowired
    private CarInjectMapper carInjectMapper;

    @Test
    public void shouldMapCarToDto() {
        Car car = new Car("Morris", 5, "Sedan");
        CarDto carDto = carInjectMapper.carToCarDto(car);
        assertEquals("Morris", carDto.getMake());
        assertEquals(5, carDto.getSeatCount());
        assertEquals("Sedan", carDto.getType());
    }
}

查看生成的实现类 CarInjectMapperImpl，可以看到这个类被 Spring 的 @Component 注解标记。

4. 数据类型转换

在许多情况下，MapStruct 会自动处理类型转换。

例如，一个属性在源 Bean 中是 int 类型，但在目标 Bean 中是 String 类型，通过生成的代码可以看到分别调用 String.valueOf(int) 和 Integer.parseInt(String) 两个方法进行了类型的转换。

又比如在 Car 类型中有一个 Person 类型的 driver 属性，当对 Car 进行映射时，应当把 driver 映射为 PersonDto 类型。

4.1 隐式类型转换

在此列举一些常见的自动类型转换：

• Java 基本数据类型和其对应的包装类之间。把包装类转换成基本数据类型时，会执行 null 值检查
• Java 基本数据类型和封装类型之间。例如 int 和 long 之间或 byte 和 Integer 之间

注意： 从精度较大类型的数据转换为精度较小的数据时，可能会造成值或精度缺失（例如从 long 转换为 int）。@Mapper 和 @MapperConfig 注解有一个属性 typeConversionPolicy 来控制警告或错误，其默认值为 ReportingPolicy.IGNORE。

• 基本数据类型及其包装类和 String 之间。可以在 @Mapping 的 numberFormat 属性中指定 java.text.DecimalFormat 能理解的格式化字符串对数值格式化

123456789@Mapper
public interface CarMapper {

    @Mapping(source = "price", numberFormat = "$#.00")
    CarDto carToCarDto(Car car);

    @IterableMapping(numberFormat = "$#.00")
    List<String> prices(List<Integer> prices);
}

• enum 和 String 之间

• 大数类型（java.math.BigInteger，java.math.BigDecimal）和基本数据类型（及其包装类）以及 String 之间。同样可以使用 @Mapping 的 numberFormat 属性对数值格式化

1234567@Mapper
public interface CarMapper {

    @Mapping(source = "power", numberFormat = "#.##E0")
    CarDto carToCarDto(Car car);

}

• JAXBElement<T> 和 T 之间，List<JAXBElement<T>> 和 List<T> 之间
• java.util.Calendar 或 java.util.Date 和 JAXB 的 XMLGregorianCalendar 之间
• java.util.Date 日期类型或 XMLGregorianCalendar 和 String 之间。可以在 @Mapping 的 dateFormat 属性中指定 java.text.SimpleDateFormat 能理解的格式化字符串对日期字符串格式化

123456789@Mapper
public interface CarMapper {

    @Mapping(source = "manufacturingDate", dateFormat = "dd.MM.yyyy")
    CarDto carToCarDto(Car car);

    @IterableMapping(dateFormat = "dd.MM.yyyy")
    List<String> stringListToDateList(List<Date> dates);
}

• Jodas 中的日期时间类型（DateTime、LocalDateTime、LocalDate、LocalTime）和 String 之间。可以使用 @Mapping 的 dateFormat 属性对数值进行格式化

• Jodas 的 DateTime 类型和 javax.xml.datatype.XMLGregorianCalendar、java.util.Calendar 之间

• Jodas 的 LocalDateTime、LocalDate 和 javax.xml.datatype.XMLGregorianCalendar、java.util.Date 之间

• java.time.LocalDate、java.time.LocalDateTime 和 javax.xml.datatype.XMLGregorianCalendar 之间

• Java 8 日期时间类型（ZonedDateTime、LocalDateTime、LocalDate、LocalTime）和 String 之间。可以使用 @Mapping 的 dateFormat 属性对数值进行格式化

• Java 8 日期类型（Instant、Duration、Period）和 String 之间

• Java 8 的 ZonedDateTime 类型和 Date 之间，当从给定的 Date 转换成 ZonedDateTime 时，使用系统默认时区

• Java 8 的 LocalDateTime 类型和 Date 之间，使用 UTC 作为时区

• Java 8 的 LocalDate 类型和 java.util.Date、java.sql.Date 之间，使用 UTC 作为时区

• Java 8 的 Instant 类型和 Date 之间

• Java 8 的 ZonedDateTime 类型和 Calendar 之间

• java.sql.Date、java.sql.Time、java.sql.Timestamp 和 java.util.Date 之间

• 当从一个字符串转换时，如果省略 @Mapping 注解的 dateFormat，会使用默认的格式和符号来转换，但 XmlGregorianCalendar 是个例外，将根据 XML Schema 1.0 Part 2, Section 3.2.7-14.1, Lexical Representation

• java.util.Currency 和 String 之间。当从一个字符串转换时，其值应符合 ISO-4217 规范，否则会抛出 IllegalArgumentException 异常

• java.util.UUID 和 String 之间。当从一个字符串转换时，其值应该是一个有效的 UUID，否则会抛出 IllegalArgumentException 异常

• String 和 StringBuilder 之间

• java.net.URL 和 String 之间。当从一个字符串转换时，其值应该是一个有效的 URL，否则会抛出 MalformedURLException 异常

4.2 映射对象引用

通常，一个对象不仅具有基本数据类型的属性，还引用其他对象。比如，一个 Cage 实体内部含有 Animal 类型的属性，表示笼子里关着的动物。

在这种情况下，也只需为引用的对象类型定义一个映射方法。

具体使用

创建一个新的 Cage 实体：

12345678910/**
 * @author mofan 2021/2/7
 */
@Setter
@Getter
public class Cage {
    private String name;
    private String size;
    private Animal animal;
}

将映射成的 CageDto 实体：

12345678910/**
 * @author mofan 2021/2/7
 */
@Getter
@Setter
public class CageDto {
    private String name;
    private String size;
    private DogDto dog;
}

用于实体映射的接口：

12345678910111213/**
 * @author mofan 2021/2/7
 */
@Mapper
public interface CageMapper {

    CageMapper INSTANCE = Mappers.getMapper(CageMapper.class);

    @Mapping(source = "animal", target = "dog")
    CageDto toCageDto(Cage cage);

    DogDto toDogDto(Animal animal);
}

测试方法：

12345678910111213@Test
public void testToCageDto() {
    Cage cage = new Cage();
    Animal animal = new Animal("小黑", "Dog");
    cage.setAnimal(animal);
    cage.setName("小黑的家");
    cage.setSize("70*50*60");
    CageDto cageDto = CageMapper.INSTANCE.toCageDto(cage);
    Assert.assertEquals("小黑的家", cageDto.getName());
    Assert.assertEquals("70*50*60", cageDto.getSize());
    Assert.assertEquals("小黑", cageDto.getDog().getName());
    Assert.assertEquals("Dog", cageDto.getDog().getType());
}

运行测试方法后，测试通过。

查看生成的实现类 CageMapperImpl 接口实现类：

12345678910111213141516171819202122232425262728293031public class CageMapperImpl implements CageMapper {

    @Override
    public CageDto toCageDto(Cage cage) {
        if ( cage == null ) {
            return null;
        }

        CageDto cageDto = new CageDto();

        cageDto.setDog( toDogDto( cage.getAnimal() ) );
        cageDto.setName( cage.getName() );
        cageDto.setSize( cage.getSize() );

        return cageDto;
    }

    @Override
    public DogDto toDogDto(Animal animal) {
        if ( animal == null ) {
            return null;
        }

        DogDtoBuilder dogDto = DogDto.builder();

        dogDto.name( animal.getName() );
        dogDto.type( animal.getType() );

        return dogDto.build();
    }
}

MapStruct 对源对象与目标对象属性的映射规则

1. 如果源属性和目标属性类型相同，值将直接从源复制到目标。如果属性是一个集合（如 List），集合的副本（新建一个集合，然后把源数据一个个地塞进去）将被设置到目标属性中。

2. 如果源属性和目标属性类型不同，将在当前类检查是否存在将源属性的类型作为参数类型，将目标属性的类型作为返回类型的另一种映射方法。如果存在这样的方法，它将在生成的实现方法中被调用。

3. 如果不存在这样的方法，MapStruct 将查看源属性类型和目标属性类型是否存在内置转换。如果存在，生成的代码将采用这种转换。

4. 如果不存在这样的方法，MapStruct 将采用复杂的转换：

   • 映射方法，通过映射方法映射结果，比如：target = method1(method2(source))
   • 内置转换，通过映射方法映射结果，比如：target = method(conversion(source))
   • 映射方法，通过内置转换映射结果，比如：target = conversion(method(source))

5. 如果没有找到这样的方法，MapStruct 将尝试生成一个自动的 sub-mapping 方法，使用方法进行源属性和目标属性之间的映射。

6. 如果 MapStruct 无法创建基于名称的映射方法，则会在编译时引发错误，显示不可映射的属性及其路径。

可以在以下四个注解上设置 mappingControl（映射控件），优先级依次增加：

• @MapperConfig
• @Mapper
• @BeanMapping
• @Mapping

比如 @Mapper(mappingControl = NoComplexMapping.class) 的优先级高于 @MapperConfig(mappingControl = DeepClone.class)。

@IterableMapping 和 @MapMapping 的工作原理与 @Mapping 类似。

映射控件是在 MapStruct 1.4 中引入的实验性功能。

映射控件的类型由枚举 org.mapstruct.control.MappingControl.Use 表示：

• BUILT_IN_CONVERSION
• COMPLEX_MAPPING
• DIRECT
• MAPPING_METHOD

枚举 Use 的存在使得用户可以对 MapStruct 的映射细节进行控制，当缺失某种枚举时，表示关闭对应的映射方式，默认情况下 mappingControl = MappingControl.class，表示启用所有映射选项。

属性间应用拓展

1. 如果不想让 MapStruct 生成自动的 sub-mapping 方法，可以使用：

1@Mapper(disableSubMappingMethodsGeneration = true)

2. 用户可以通过元注解来控制映射。提供了一些方便的注解，比如 @DeepClone 只允许直接映射。使用该注解后，如果源类型和目标类型相同，MapStruct 将对源类型进行深拷贝。sub-mappings-methods 必须被允许（默认情况下）。
3. 在自动的 sub-mapping 方法生成过程中，共享配置将不会被考虑在内。
4. 目标对象的构造函数属性也被视为目标属性。

4.3 控制嵌套对象映射

MapStruct 会使用源属性名和目标属性名生成映射方法，但不幸的是，这两个名称通常不会相等。在这这种情况下，需要使用 @Mapping 注解来指定属性之间的映射。

比如：

12345678910@Mapper
public interface FishTankMapper {
    @Mapping(target = "fish.kind", source = "fish.type")
    @Mapping(target = "fish.name", ignore = true)
    @Mapping(target = "ornament", source = "interior.ornament")
    @Mapping(target = "material.materialType", source = "material")
    @Mapping(target = "quality.report.organisation.name", 
             source = "quality.report.organisationName")
    FishTankDto map( FishTank source );
}

再或者：

1234567891011@Mapper
public interface FishTankMapperWithDocument {
    @Mapping(target = "fish.kind", source = "fish.type")
    @Mapping(target = "fish.name", expression = "java(\"Jaws\")")
    @Mapping(target = "plant", ignore = true )
    @Mapping(target = "ornament", ignore = true )
    @Mapping(target = "material", ignore = true)
    @Mapping(target = "quality.document", source = "quality.report")
    @Mapping(target = "quality.document.organisation.name", constant = "NoIdeaInc" )
    FishTankWithNestedDocumentDto map( FishTank source );
}

MapStruct 将对源对象中的每个嵌套属性执行 null 检查。

MapStruct 鼓励用户编写明确的 嵌套属性映射方法，而不是通过 @Mapping 配置来解决一切，这样还可以实现代码复用，更加优雅~ 👊

在某些情况下，用于生成嵌套方法的 ReportingPolicy 可能是 IGNORE，这意味着 MapStruct 不会显示嵌套映射中未映射的目标属性。

4.4 执行自定义映射方法

有时映射并不简单，有些字段可能需要自定义逻辑。

比如将 FishTank 中的 length、width 和 height 属性映射到 FishTankWithVolumeDto 中的 volume 属性，这个映射也不是一个简单的映射，需要计算鱼缸 FishTank 的体积，然后输出描述信息。

参与转换的类：

123456789101112131415161718192021222324252627282930313233343536373839/**
 * @author mofan 2021/2/7
 */
@Getter
@Setter
public class FishTank {
    private Fish fish;
    private int length;
    private int width;
    private int height;
}

@Getter
@Setter
@AllArgsConstructor
public class VolumeDto {
    private int volume;
    private String description;
}

@Getter
@Setter
public class FishTankWithVolumeDto {
    private FishDto fish;
    private VolumeDto volume;
}

@Getter
@Setter
public class Fish {
    private String type;
}

@Getter
@Setter
public class FishDto {
    private String kind;
    private String name;
}

用于实体映射的抽象类（换一种方法，不要接口）：

123456789101112131415161718192021222324252627/**
 * @author mofan 2021/2/7
 */
@Mapper
public abstract class FishTankMapperWithVolume {

    public static FishTankMapperWithVolume INSTANCE
            = Mappers.getMapper(FishTankMapperWithVolume.class);

    /**
     * <p>将 FishTank 转换为 FishTankWithVolumeDto</p>
     * <code>@Mapping</code> 注解的 source 属性值是 map() 方法的参数,
     * 而不是 FishTank 中的属性
     *
     * @param source FishTank实例
     * @return FishTankWithVolumeDto 实例
     */
    @Mapping(target = "fish.kind", source = "source.fish.type")
    @Mapping(target = "volume", source = "source")
    public abstract FishTankWithVolumeDto map(FishTank source);

    protected VolumeDto mapVolume(FishTank source) {
        int volume = source.getLength() * source.getWidth() * source.getHeight();
        String desc = volume < 100 ? "Small" : "Large";
        return new VolumeDto(volume, desc);
    }
}

@Mapping 注解的 source 属性值是 map() 方法的参数 source，而不是 FishTank 中名为 source 的属性。

测试方法：

12345678910111213141516171819/**
 * @author mofan 2021/2/7
 */
public class FishTankMapperWithVolumeTest {
    @Test
    public void testToFishTankWithVolumeDto() {
        FishTank fishTank = new FishTank();
        fishTank.setLength(70);
        fishTank.setWidth(50);
        fishTank.setHeight(60);
        Fish fish = new Fish();
        fish.setType("Carp");
        fishTank.setFish(fish);
        FishTankWithVolumeDto dto = FishTankMapperWithVolume.INSTANCE.map(fishTank);
        Assert.assertEquals(210000, dto.getVolume().getVolume());
        Assert.assertEquals("Large", dto.getVolume().getDescription());
        Assert.assertEquals("Carp", dto.getFish().getKind());
    }
}

运行测试方法后，测试通过。

查看生成的实现类 FishTankMapperWithVolumeImpl 接口实现类：

12345678910111213141516171819202122232425262728public class FishTankMapperWithVolumeImpl extends FishTankMapperWithVolume {

    @Override
    public FishTankWithVolumeDto map(FishTank source) {
        if ( source == null ) {
            return null;
        }

        FishTankWithVolumeDto fishTankWithVolumeDto = new FishTankWithVolumeDto();

        fishTankWithVolumeDto.setFish( fishToFishDto( source.getFish() ) );
        fishTankWithVolumeDto.setVolume( mapVolume( source ) );

        return fishTankWithVolumeDto;
    }

    protected FishDto fishToFishDto(Fish fish) {
        if ( fish == null ) {
            return null;
        }

        FishDto fishDto = new FishDto();

        fishDto.setKind( fish.getType() );

        return fishDto;
    }
}

4.5 调用其他映射器

MapStruct 还可以调用其他类中定义的映射方法，这些映射方法可以是 MapStruct 生成的也可以是手动编写的。这对于在多个类中编写映射代码，或者想提供无法由 MapStruct 生成的自定义映射逻辑，是非常有用的。

调用其他映射器时，只需在 @Mapper#uses 配置想使用的映射器类即可，可以指定多个。

具体使用

假设有一属性 manufacturingDate 在源实体中的类型为 Date，而在目标实体中类型为 String，在转换过程中，对日期值按需求进行格式化，这时候就需要使用自己编写的映射器进行映射处理。

源实体：

1234567@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class Car {
    private Date manufacturingDate;
}

目标实体：

1234567@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
public class CarDto {
    private String manufacturingDate;
}

自定义的映射方法：

12345678910111213141516171819/**
 * @author mofan 2021/2/9
 */
public class DateMapper {

    public String asString(Date date) {
        return date != null ? new SimpleDateFormat("yyyy-MM-dd")
                .format(date) : null;
    }

    public Date asDate(String date) {
        try {
            return date != null ? new SimpleDateFormat("yyyy-MM-dd")
                    .parse(date) : null;
        } catch (ParseException e) {
            throw new RuntimeException(e);
        }
    }
}

由于需要使用自定义的映射方法，因此需要在 @Mapper#uses 上指定映射方法所在的类。

映射器接口：

123456789101112@Mapper(uses = DateMapper.class)
public interface CarMapper {

    CarMapper INSTANCE = Mappers.getMapper(CarMapper.class);

    /**
     * 将 Car 转换成 CarDto，不忽略 Date
     * @param car Car 实例
     * @return    对应的 DTO
     */
    CarDto carToCarDtoUseDate(Car car);
}

测试方法：

1234567@Test
public void testUseDate() {
    // 时间戳表示的时间为 2021-02-09 00:00:00
    Car car = new Car(new Date(1612800000000L));
    CarDto carDto = CarMapper.INSTANCE.carToCarDtoUseDate(car);
    assertEquals("2021-02-09", carDto.getManufacturingDate());
}

运行测试方法后，测试通过。

查看生成的实现类 CarMapperImpl 接口实现类：

1234567891011121314151617public class CarMapperImpl implements CarMapper {
    private final DateMapper dateMapper = new DateMapper();

    public CarMapperImpl() {
    }

    public CarDto carToCarDtoUseDate(Car car) {
        if (car == null) {
            return null;
        } else {
            CarDto carDto = new CarDto();
            carDto.setManufacturingDate(this.dateMapper
                                        .asString(car.getManufacturingDate()));
            return carDto;
        }
    }
}

在为实现 carToCarDto() 方法生成代码时，MapStruct 将寻找一个将 Date 对象映射为 String 的方法，最终在 DateMapper 类中找到它，使用其中的 asString() 方法来映射不同类型的 manufacturingDate 属性。

总结思考

生成的映射器使用为其配置的组件模型（使用 @Mapper#componentModel 配置组件模型）获取引用的映射器。

在示例代码生成的映射器实现类中，使用了 new 关键词 调用无参构造方法 创建了一个包含自定义映射方法的对象。

因此，默认情况下， 在自定义映射方法的所在类中，一定要含有公共无参构造方法，以便能够被实例化。

在使用了依赖注入时，自定义映射方法的所在类也要是一个可注入的 Bean。比如使用了 Spring 框架时，需要让自定义映射方法的所在类也被 Spring 管理。

4.6 将目标类型传递给自定义映射器

使用 @Mapper#uses() 将自定义映射器与生成的映射器挂钩时，可以在自定义映射方法中定义 Class 类型（或其超类）的附加参数，以便针对特定的目标对象类型执行常规映射任务。该属性必须使用 @TargetType 进行标注，以便 MapStruct 生成与目标对象中属性对应类型一致的 Class 实例。

例如，CarDto 中有一个 Reference 类型的 owner 属性，它包含了 Person 实体的主键。现在可以创建通用的自定义映射器，将任何 Reference 对象解析为其对应的、由 JPA 管理的实体实例。

123456789101112131415161718192021@ApplicationScoped // CDI component model
public class ReferenceMapper {

    @PersistenceContext
    private EntityManager entityManager;

    public <T extends BaseEntity> T resolve(Reference reference, 
                                            @TargetType Class<T> entityClass) {
        return reference != null ? 
            entityManager.find(entityClass, reference.getPk()) : null;
    }

    public Reference toReference(BaseEntity entity) {
        return entity != null ? new Reference( entity.getPk() ) : null;
    }
}

@Mapper(componentModel = "cdi", uses = ReferenceMapper.class )
public interface CarMapper {
    Car carDtoToCar(CarDto carDto);
}

生成的代码：

123456789101112131415161718192021//GENERATED CODE
@ApplicationScoped
public class CarMapperImpl implements CarMapper {

    @Inject
    private ReferenceMapper referenceMapper;

    @Override
    public Car carDtoToCar(CarDto carDto) {
        if ( carDto == null ) {
            return null;
        }

        Car car = new Car();

        car.setOwner( referenceMapper.resolve( carDto.getOwner(), Owner.class ) );
        // ...

        return car;
    }
}

4.7 传递上下文或状态对象给自定义方法

可以通过生成的映射方法将额外上下文或状态信息传递给具有 @Context 参数的自定义方法。

这样的参数会传递给其他映射方法、适用的情况下的 @ObjectFactory 方法或 @BeforeMapping、@AfterMapping 方法，因此可以在自定义代码中使用。

在 @ObjectFactory 方法中搜索被 @Context 标记的参数，如果适用，将根据提供的上下文参数值调用这些方法。

还会在 @BeforeMapping、@AfterMapping 方法中搜索被 @Context 标记的参数，如果适用，将根据提供的上下文参数值调用这些方法。

注意：在调用传入上下文参数的映射方法之前，不会进行 空检查。在这种情况下，调用方需要确保没有传入 null。

为了在生成的代码中能够调用含有 @Context 参数的自定义方法，正在生成的映射方法的声明中也需要包含这些（或子类）@Context 参数。生成的代码中不会为缺少的 @Context 参数创建新的实例，也不会传递一个空值代替。

具体使用

使用 @Context 参数将数据传递给我们自定义的属性映射方法：

123456public abstract CarDto toCar(Car car, @Context Locale translationLocale);

protected OwnerManualDto translateOwnerManual(OwnerManual ownerManual, 
                                              @Context Locale locale) {
    // manually implemented logic to translate the OwnerManual with the given Locale
}

生成的代码：

12345678910111213//GENERATED CODE
public CarDto toCar(Car car, Locale translationLocale) {
    if ( car == null ) {
        return null;
    }

    CarDto carDto = new CarDto();

    carDto.setOwnerManual( translateOwnerManual( car.getOwnerManual(), translationLocale );
    // more generated mapping code

    return carDto;
}

4.8 映射方法的解析

将属性从一种类型映射到另一种类型时，MapStruct 寻找将源类型映射到目标类型的最明确的方法。该方法可以是在同一个映射器接口中声明的，也可以是通过 @Mapper#uses() 注册的另一个映射器中声明的。这同样适用于工厂方法。

寻找映射方法或工厂方法的算法与 Java 的方法解析算法很类似，尤其是具有更明确源类型的方法都将被优先获取（假如有两个方法，一个方法映射寻找的源类型，另一个映射相同的父类型）。如果有多个详细程度相当的方法时，则会引发错误。

在使用 JAXB 时，比如将 String 转换为对应的 JAXBElement<String> 时，MapStruct 在寻找映射方法时将考虑 @XmlElementDecl 注解的 scope 和 name 属性值，这将确保创建的 JAXBElement 实例具有正确的 QNAME 值。

4.9 基于限定符的映射方法选择

在很多情况下需要具有相同方法签名（除了名称）但具有不同行为的映射方法。

MapStruct 提供 @Qualifier（org.mapstruct.Qualifier）注解来处理这种情况。一个「qualifier」（可译为「限定符」）可以是用户自定义的一个注解，这个注解作用在一个能被使用的映射器中的映射方法上，这个映射方法可以在对象属性映射、iterable 映射或 map 映射中被引用。一个方法和映射器上可以有多个限定符。

具体使用

假设有一个手写的映射器 Titles，其内部有多个参数类型是 String，返回值类型也是 String 的自定义映射方法：

12345678910public class Titles {

    public String translateTitleEG(String title) {
        // some mapping logic
    }

    public String translateTitleGE(String title) {
        // some mapping logic
    }
}

在 Mapper 接口中需要使用到前文中手写的映射器：

1234@Mapper(uses = Titles.class)
public interface MovieMapper {
    GermanRelease toGerman(OriginalRelease movies);
}

但这样是有问题的，因为在手写的映射器中有多个符合条件的映射方法，MapStruct 无法区分。

这个时候需要使用到 @Qualifier 注解。

编写一个注解，这个注解作用于 手写的映射器 上，将 @Qualifier 作为元注解使用：

1234567import org.mapstruct.Qualifier;

@Qualifier
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.CLASS)
public @interface TitleTranslator {
}