Bean转换工具MapStruct看这一篇就够了

内容持续更新中…

文章目录

1.背景
2.mapstruct简介
3.mapstruct与其他映射对比
4.mapstruct底层原理解析
5.具体使用和底层实现
- 5.1 添加maven依赖
- 5.2 对象转换
- - 1.UserA和UserB字段相同
  - 2.UserA和UserB字段不同
  - 3.多个源类
  - 4.子对象映射
  - 5.数据类型转换
  - - 数据类型映射
    - 枚举映射
  - 6.集合映射
  - - List映射
    - Set和Map映射
    - 集合映射策略
- 5.3 依赖注入
- 5.4 默认值
- - 3.Mapper中的自定义转换

1.背景

在我们日常开发的分层结构的应用程序中，为了各层之间互相解耦，一般都会定义不同的对象用来在不同层之间传递数据，因此，就有了各种 XXXDTO、XXXVO、XXXBO 等基于数据库对象派生出来的对象，当在不同层之间传输数据时，不可避免地经常需要将这些对象进行相互转换。

此时一般处理两种处理方式：

① 直接使用 Setter 和 Getter 方法转换
② 使用一些工具类进行转换（e.g. BeanUtil.copyProperties）。

第一种方式如果对象属性比较多时，需要写很多的 Getter/Setter 代码。第二种方式看起来虽然比第一种方式要简单很多，但是因为其使用了反射，性能不太好，而且在使用中也有很多陷阱。而今天要介绍的主角 MapStruct 在不影响性能的情况下，同时解决了这两种方式存在的缺点。

2.mapstruct简介

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
mapstruct是一种实体类映射框架，能够通过Java注解将一个实体类的属性安全地赋值给另一个实体类。它基于约定优于配置方法极大地简化了 Java bean 类型之间映射的实现，有了mapstruct，只需要定义一个映射器接口，声明需要映射的方法，在编译过程中，mapstruct会自动生成该接口的实现类，实现将源对象映射到目标对象的效果。

总的来说，有如下三个特点：

基于注解
在编译期自动生成映射转换代码
类型安全、高性能、无依赖性

源码地址：https://github.com/mapstruct/mapstruct

mapstruct底层原理解析

3.mapstruct与其他映射对比

在第一章我们也提到，实体类映射框架大致有两种：

一种是运行期通过java反射机制动态映射；
另一种是编译期动态生成getter/setter，在运行期直接调用框架编译好的class类实现实体映射。

由于mapstruct映射是在编译期间实现的，因此相比运行期的映射框架有以下几个优点：

1.安全性高。因为是编译期就实现源对象到目标对象的映射，如果编译器能够通过，运行期就不会报错。
2.速度快。速度快指的是运行期间直接调用实现类的方法，不会在运行期间使用反射进行转化。

此处我们先不讲原理，先看一下MapStruct具体的用法，感受一下其魅力所在，然后再看一下它的底层到底是怎么样实现的

4.mapstruct底层原理解析

mapstruct是基于JSR 269实现的，JSR 269是JDK引进的一种规范。有了它，能够实现在编译期处理注解，并且读取、修改和添加抽象语法树中的内容。

JSR 269使用Annotation Processor在编译期间处理注解，Annotation Processor相当于编译器的一种插件，因此又称为插入式注解处理。想要实现JSR 269，主要有以下几个步骤：

1.继承AbstractProcessor类，并且重写process方法，在process方法中实现自己的注解处理逻辑。
2.在META-INF/services目录下创建javax.annotation.processing.Processor文件注册自己实现的Annotation Processor

说到此处就不得不提一下Java程序编译的流程：
外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
上图中Java源码到class文件的过程其实是一个比较复杂的过程。其中的经过可以用下图描述：

上图的流程可以概括为下面几个步骤：

1.生成抽象语法树。Java编译器对Java源码进行编译，生成抽象语法树（Abstract Syntax Tree，AST）。
2.调用实现了JSR 269 API的程序。只要程序实现了JSR 269 API，就会在编译期间调用实现的注解处理器。
3.修改抽象语法树。在实现JSR 269 API的程序中，可以修改抽象语法树，插入自己的实现逻辑。
4.生成字节码。修改完抽象语法树后，Java编译器会生成修改后的抽象语法树对应的字节码文件件。

5.具体使用和底层实现

5.1 添加maven依赖

	<properties>
		<org.mapstruct.version>1.5.5.Final</org.mapstruct.version>
	</properties>
		<dependency>
			<groupId>org.mapstruct</groupId>
			<artifactId>mapstruct</artifactId>
			<version>${org.mapstruct.version}</version>
		</dependency>
		<dependency>
			<groupId>org.mapstruct</groupId>
			<artifactId>mapstruct-processor</artifactId>
			<version>${org.mapstruct.version}</version>
		</dependency>

5.2 对象转换

我们直接创建两个对象：
UserA，UserB，然后我们将AB进行互转

此时UserA和UserB有两种情景：

1.UserA和UserB字段相同

@Data
public class UserA {
    private Integer id;
    private String name;
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
创建对象转换器（Mapper）
需要注意的是，转换器不一定都要使用 Mapper 作为结尾，只是官方示例推荐以 XXXMapper 格式命名转换器名称，这里举例的是最简单的映射情况（字段名称和类型都完全匹配），只需要在转换器类上添加 @Mapper 注解即可，转换器代码如下所示：

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    UserB toUserB(UserA userA);

}

调用Mapper进行对象的转换

@SpringBootTest
class DemoApplicationTests {
	@Test
	void test1(){
		Integer id = 1;
		String name = "ninesun";

		UserA userA = new UserA();
		userA.setId(id);
		userA.setName(name);

		UserB userB = UserMapper.INSTANCE.toUserB(userA);
		assertEquals(id, userB.getId());
		assertEquals(name, userB.getName());
	}
}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
可以看到测试通过

编译之后，MapStruct注解处理器插件会识别出DoctorMapper接口并为其生成一个实现类。
，在Mapper上就可以看见其具体的实现
外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

可以看到UserMapperImpl类中包含一个toUserB()方法，里面它帮我们实现了字段的映射，最终实现了UserA到UserB的转换

2.UserA和UserB字段不同

如果两者字段名称不同，MapStuct无法做到直接进行映射，需要将字段不一致的地方借助@Mappings进行对应
我们先创建一个对象UserC

@Data
public class UserC {
    private Integer id;
    private String userName;
}

和UserA相比发现name字段其实是无法映射的
外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
只需要在Mapper里加入toUserC的方法即可

UserC toUserC(UserA userA);

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
进行一下测试

	@Test
	void test2(){
		Integer id = 1;
		String name = "ninesun";

		UserA userA = new UserA();
		userA.setId(id);
		userA.setName(name);

		UserC userC = UserMapper.INSTANCE.toUserC(userA);
		assertEquals(id, userC.getId());
		assertEquals(name, userC.getUserName());
	}

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
可以发现UserC的name并没有转换成功，原因就是UserA中的name无法和UserBC中的userName字段进行映射

怎么办呢？

方法也很简单

    @Mappings({
            @Mapping(source = "name", target = "userName"),
    })
    UserC toUserC(UserA userA);

只需要我们手动去实现映射即可，再次允许Test2方法进行测试，可以发现测试可以通过
外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
上面我们已经提到了@Mapping属性中的source和target，除此之外，他还有几个基本属性：

ignore：表示忽略映射当前字段
- true：忽略该字段
- false：不忽略，默认为false
defaultValue 默认值

    @Mapping(source = "UserA.specialty", target = "specialization", defaultValue = "Information Not Available")

expressions 可以通过表达式来构造一些简单的转化关系
虽然设计的时候想兼容很多语言，不过目前只能写Java代码。

上面均是一对一的情况，即一个对象和一个对象之间的互转，多对一的场景我们一起看一下是什么样子的

3.多个源类

我们新增两个对象UserDto、Education

@Data
public class UserDto {
    private Integer id;
    private String name;

    private String degree;
}

@Data
public class Education {
    private String degreeName;
    private String institute;
    private Integer yearOfPassing;
}

我们接下来需要做的便是将UserA和Education中的属性值映射到UserDto中，对应的UserMapper中的内容如下：

    @Mappings({
            @Mapping(source = "userA.name", target = "userName"),
            @Mapping(source = "education.degreeName", target = "degree"),
    })
    UserDto toUserDto(UserA userA, Education education);

接下来继续测试

    @Test
    void test5() {
        Integer id = 1;
        String name = "ninesun";
        String degreeName = "博士";
        UserA userA = new UserA();
        userA.setId(id);
        userA.setName(name);
        Education education = new Education();
        education.setDegreeName(degreeName);
        UserDto userDto = UserMapper.INSTANCE.toUserDto(userA, education);
        System.out.println(JSON.toJSONString(userDto));
    }

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

4.子对象映射

多数情况下，POJO中不会只包含基本数据类型，其中往往会包含其它类。比如说，一个User类中会有多门课程：

@Data
public class UserA {
    private Integer id;
    private String name;
    private List<Course> courseList;
}

@Data
public class Course {
    private String name;
    private Integer time;
}

@Data
public class UserDto {
    private Integer id;
    private String userName;
    private String degree;
    private List<CourseDto> courseDtoList;
}

@Data
public class CourseDto {
    private String name;
    private Integer time;
}

对应的Mapper如下：

    @Mappings({
            @Mapping(source = "name", target = "userName"),
            @Mapping(source = "courseList", target = "courseDtoList"),
    })
    UserDto toUserDto(UserA userA);

写个单元测试进行测试：

    @Test
    void test6() {
        Integer id = 1;
        String name = "ninesun";
        UserA userA = new UserA();
        userA.setId(id);
        userA.setName(name);
        Course course = new Course();
        course.setName("高等数学");
        course.setTime(12);
        List<Course> courseList = Arrays.asList(course);
        userA.setCourseList(courseList);
        UserDto userDto = UserMapper.INSTANCE.toUserDto(userA);
        System.out.println(JSON.toJSONString(userDto));
    }

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

5.数据类型转换

数据类型映射

MapStruct支持source和target属性之间的数据类型转换。它还提供了基本类型及其相应的包装类之间的自动转换。
自动类型转换适用于：

基本类型及其对应的包装类之间。比如， int 和 Integer， float 和 Float， long 和 Long，boolean 和 Boolean 等。
任意基本类型与任意包装类之间。如 int 和 long， byte 和 Integer 等。
所有基本类型及包装类与String之间。如 boolean 和 String， Integer 和 String， float 和 String 等。
枚举和String之间。
Java大数类型(java.math.BigInteger， java.math.BigDecimal) 和Java基本类型(包括其包装类)与String之间。
其它情况详见MapStruct官方文档

因此，在生成映射器代码的过程中，如果源字段和目标字段之间属于上述任何一种情况，则MapStrcut会自行处理类型转换。

我们修改 UserA ，新增一个birthdate字段：

@Data
public class UserA {
    private Integer id;
    private String name;
    private LocalDate birthdate;
    private List<Course> courseList;
}

UserDto中增加一个String类型的birthdate;

@Data
public class UserDto {
    private Integer id;
    private String userName;
    private String degree;
    private String birthdate;
    private List<CourseDto> courseDtoList;
}

Mapper映射

    @Mappings({
            @Mapping(source = "name", target = "userName"),
            @Mapping(source = "courseList", target = "courseDtoList"),
            @Mapping(source = "birthdate", target = "birthdate", dateFormat = "dd/MMM/yyyy"),
    })
    UserDto toUserDto(UserA userA);

测试：

    @Test
    void test7() {
        Integer id = 1;
        String name = "ninesun";
        UserA userA = new UserA();
        userA.setId(id);
        userA.setName(name);
        userA.setBirthdate(LocalDate.now());
        Course course = new Course();
        course.setName("高等数学");
        course.setTime(12);
        List<Course> courseList = Arrays.asList(course);
        userA.setCourseList(courseList);
        UserDto userDto = UserMapper.INSTANCE.toUserDto(userA);
        System.out.println(JSON.toJSONString(userDto));
    }

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
除此之外，对于数字的转换，也可以使用numberFormat指定显示格式：

   // 数字格式转换示例
   @Mapping(source = "price", target = "price", numberFormat = "$#.00")

枚举映射

枚举映射的工作方式与字段映射相同。MapStruct会对具有相同名称的枚举进行映射，这一点没有问题。但是，对于具有不同名称的枚举项，我们需要使用@ValueMapping注解。同样，这与普通类型的@Mapping注解也相似。

我们先创建两个枚举。

public enum PaymentType {
    CASH,
    CHEQUE,
    CARD_VISA,
    CARD_MASTER,
    CARD_CREDIT
}

public enum PaymentTypeView {
    CASH,
    CHEQUE,
    CARD
}

单元测试：

    @Test
    void test8() {
        PaymentType paymentType1=PaymentType.CASH;
        PaymentType paymentType2=PaymentType.CARD_VISA;
        PaymentTypeView paymentTypeView1=PaymentTypeMapper.INSTANCE.paymentTypeToPaymentTypeView(paymentType1);
        PaymentTypeView paymentTypeView2=PaymentTypeMapper.INSTANCE.paymentTypeToPaymentTypeView(paymentType2);
        System.out.println(paymentTypeView1);
        System.out.println(paymentTypeView2);
    }

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
但是，如果你要将很多值转换为一个更一般的值，这种方式就有些不切实际了。其实我们不必手动分配每一个值，只需要让MapStruct将所有剩余的可用枚举项（在目标枚举中找不到相同名称的枚举项），直接转换为对应的另一个枚举项。

可以通过 MappingConstants实现这一点：

@ValueMapping(source = MappingConstants.ANY_REMAINING, target = "CARD")
PaymentTypeView paymentTypeToPaymentTypeView(PaymentType paymentType);

还有一种选择是使用ANY UNMAPPED：

@ValueMapping(source = MappingConstants.ANY_UNMAPPED, target = "CARD")
PaymentTypeView paymentTypeToPaymentTypeView(PaymentType paymentType);

采用这种方式时，MapStruct不会像前面那样先处理默认映射，再将剩余的枚举项映射到target值。而是，直接将所有未通过@ValueMapping注解做显式映射的值都转换为target值。

6.集合映射

使用MapStruct处理集合映射的方式与处理简单类型相同

MapStruct将根据我们的声明自动生成映射代码。通常，生成的代码会遍历源集合，将每个元素转换为目标类型，并将每个转换后元素添加到目标集合中。

List映射

如果我们的Mapper中饭只有下面这一个方法

List<UserDto> map(List<UserA> userAList);

测试：

    @Test
    void test9() {
        Integer id = 1;
        String name = "ninesun";
        UserA userA = new UserA();
        userA.setId(id);
        userA.setName(name);
        userA.setBirthdate(LocalDate.now());
        Course course = new Course();
        course.setName("高等数学");
        course.setTime(12);
        List<Course> courseList = Arrays.asList(course);
        userA.setCourseList(courseList);
        List<UserA> userAList = Arrays.asList(userA);
        List<UserDto> userDtoList = UserMapper.INSTANCE.map(userAList);
        System.out.println(JSON.toJSONString(userDtoList));
    }

外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
可以发现字段名称不一致的均未转换，这个时候我们把实体和实体之间的字段映射加进去

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);
    @Mappings({
            @Mapping(source = "name", target = "userName"),
            @Mapping(source = "courseList", target = "courseDtoList"),
            @Mapping(source = "birthdate", target = "birthdate", dateFormat = "dd/MMM/yyyy"),
    })
    UserDto toUserDto(UserA userA);

    List<UserDto> map(List<UserA> userAList);
}

再次运行刚刚的测试用例，可以发现所有的字段映射成功
外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传

Set和Map映射

Set与Map型数据的处理方式与List相似。按照以下方式修改UserMapper：

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    Set<UserDto> setConvert(Set<UserA> doctor);

    Map<String, UserDto> mapConvert(Map<String, UserA> doctor);
}

同样，我们如果只要这些映射，字段名称不同的仍然无法映射，所以同样需要加入

   @Mappings({
            @Mapping(source = "name", target = "userName"),
            @Mapping(source = "courseList", target = "courseDtoList"),
            @Mapping(source = "birthdate", target = "birthdate", dateFormat = "dd/MMM/yyyy"),
    })
    UserDto toUserDto(UserA userA);

来处理单个对象字段不一致的情况

集合映射策略

@Data
public class UserA {
    private Integer id;
    private String name;
    private LocalDate birthdate;
    private List<Course> courseList;
}

@Data
public class UserDto {
    private Integer id;
    private String userName;
    private String degree;
    private String birthdate;
    private List<CourseDto> courseDtoList;

    public void setCourseDtoList(List<CourseDto> courseDtoList) {
        this.courseDtoList = courseDtoList;
    }

    public void addCourseDto(CourseDto courseDto) {
        if (courseDtoList == null) {
            courseDtoList = new ArrayList<>();
        }
        courseDtoList.add(courseDto);
    }

}

可以发现UserDto中多了一个set方法和add方法

    @Mappings({
            @Mapping(source = "name", target = "userName"),
            @Mapping(source = "courseList", target = "courseDtoList"),
            @Mapping(source = "birthdate", target = "birthdate", dateFormat = "dd/MMM/yyyy"),
    })
    UserDto toUserDto(UserA userA);

编译之后的实现类：
外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
可以看到，在默认情况下采用的策略是ACCESSOR_ONLY，使用setter方法setCourseDtoList()向UserDto对象中写入列表数据。

相对的，如果使用 ADDER_PREFERRED 作为映射策略：

@Mapper(collectionMappingStrategy = CollectionMappingStrategy.ADDER_PREFERRED)
public interface UserMapper {}

此时，会使用adder方法逐个将转换后的子类型DTO对象加入父类型的集合字段中。
外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
如果目标DTO中既没有setter方法也没有adder方法，会先通过getter方法获取子类型集合，再调用集合的对应接口添加子类型对象。

5.3 依赖注入

到目前为止，我们一直在通过getMapper()方法访问生成的映射器：
外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
但是，如果你使用的是Spring，只需要简单修改映射器配置，就可以像常规依赖项一样注入映射器。

@Mapper(componentModel = "spring")
public interface UserMapper {}

在@Mapper注解中添加（componentModel = “spring”），是为了告诉MapStruct，在生成映射器实现类时，我们希望它能支持通过Spring的依赖注入来创建。现在，就不需要在接口中添加 INSTANCE 字段了。

此时，生成的UserMapperImpl中会带有 @Component 注解：
外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传
只要被标记为@Component，Spring就可以把它作为一个bean来处理，你就可以在其它类（如控制器）中通过@Autowire或@Resourece注解来使用它：

@SpringBootTest
class DemoApplicationTests {
    @Autowired
    UserMapper userMapper;
    @Test
    void test1() {
        Integer id = 1;
        String name = "ninesun";

        UserA userA = new UserA();
        userA.setId(id);
        userA.setName(name);

        UserB userB = userMapper.toUserB(userA);
        assertEquals(id, userB.getId());
        assertEquals(name, userB.getName());
    }
}

即使你不使用Spring框架（PS：我估计现在使用Java的同学们应该没有不使用Spring的了吧），MapStruct也支持Java CDI：

@Mapper(componentModel = "cdi")
public interface UserMapper {}

5.4 默认值

@Mapping 注解有两个很实用的标志就是常量 constant 和默认值 defaultValue 。无论source如何取值，都将始终使用常量值；如果source取值为null，则会使用默认值。

3.Mapper中的自定义转换

有时候，对于某些类型，无法通过代码生成器的形式来进行处理。那么，就需要自定义的方法来进行转换。这时候，我们可以在接口（同一个接口，后续还有调用别的 Mapper 的方法）中定义默认方法（Java8及之后）。

@Data
public class UserA {
    private Integer id;
    private String name;

    private Date birthdate;
}

@Data
public class UserB {
    private Integer id;
    private String name;
    private Date birthdate;
}