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

这一篇就够了"/>

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会自动生成该接口的实现类，实现将源对象映射到目标对象的效果。

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

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

源码地址：

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 {@Testvoid 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);

进行一下测试

	@Testvoid 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);

接下来继续测试

    @Testvoid 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);

写个单元测试进行测试：

    @Testvoid 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);

测试：

    @Testvoid 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
}

单元测试：

    @Testvoid 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);

测试：

    @Testvoid 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 {@AutowiredUserMapper userMapper;@Testvoid 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;
}