Java MapStruct

1、什么是MapStruct

1.1 JavaBean 的困扰

在开发的时候业务代码之间有很多的 JavaBean 之间的相互转化， 非常的影响观感，却又不得不存在。后来想的一个办法就是通过反射，或者自己写很多的转换器。
第一种通过反射的方法确实比较方便，但是现在无论是 BeanUtils, BeanCopier 等在使用反射的时候都会影响到性能。虽然可以进行反射信息的缓存来提高性能。但是像这种的话，需要类型和名称都一样才会进行映射，有很多时候，由于不同的团队之间使用的名词不一样，还是需要很多的手动 set/get 等功能。
第二种的话就是会很浪费时间，而且在添加新的字段的时候也要进行方法的修改。不过，由于不需要进行反射，其性能是很高的。

1.2 MapStruct 带来的改变

MapSturct 是一个生成类型安全，高性能且无依赖的 JavaBean 映射代码的注解处理器（annotation processor）。

  • 注解处理器
  • 可以生成 JavaBean 之间那的映射代码

  • 类型安全，高性能，无依赖性

    2、MapStruct 入门

    2.1 添加依赖

    1. <dependency>
    2.   <groupId>org.projectlombok</groupId>
    3.   <artifactId>lombok</artifactId>
    4.   <version>1.16.20</version>
    5.   <scope>provided</scope>
    6. </dependency>
    7. <dependency>
    8.   <groupId>org.mapstruct</groupId>
    9.   <artifactId>mapstruct-jdk8</artifactId>
    10.   <version>${org.mapstruct.version}</version>
    11. </dependency>
    12. <dependency>
    13.   <groupId>org.mapstruct</groupId>
    14.   <artifactId>mapstruct-processor</artifactId>
    15.   <version>${org.mapstruct.version}</version>
    16. </dependency>
    17. <dependency>
    18.   <groupId>cn.hutool</groupId>
    19.   <artifactId>hutool-all</artifactId>
    20.   <version>5.1.0</version>
    21. </dependency>
    22. <dependency>
    23.   <groupId>junit</groupId>
    24.   <artifactId>junit</artifactId>
    25.   <version>4.12</version>
    26.   <scope>test</scope>
    27. </dependency>

    2.2 po类

    1. @Data
    2. public class User {
    3.   private Integer id;
    4.   private String name;
    5.   private String address;
    6.   private Date birth;
    7. }

    2.3 dto类

    1. @Data
    2. public class UserDto implements Serializable {
    3.   private Integer id;
    4.   private String name;
    5.   private String address;
    6.   private Date birth;
    7. }

    2.4 创建转换接口

    1. //可以使用abstract class代替接口
    2. @Mapper
    3. public interface UserMapper {
    5.   UserDto userToUserDto(User user);
    6.   //集合
    7.   List<UserDto> userToUserDto(List<User> users);
    8. }

    2.5 测试方法

    1. @Test
    2. public void userPoToUserDto() {
    3.   User user =new User();
    4.   user.setId(1);
    5.   user.setName("myx");
    6.   user.setAddress("河北沧州");
    7.   user.setBirth(new Date());
    8.   UserMapper mapper = Mappers.getMapper(UserMapper.class);
    9.   UserDto userDto = mapper.userToUserDto(user);
    10.   System.out.println(userDto);
    11. }

    2.6 运行效果

    2021-09-04-13-56-49-437039.png

    2.7 查看编译的class

    底层通过自动取值赋值操作完成
    2021-09-04-13-56-49-702036.png

    3、MapStruct优点分析

    3.1 性能高

    这是相对反射来说的，反射需要去读取字节码的内容，花销会比较大。而通过 MapStruct 来生成的代码，其类似于人手写。速度上可以得到保证。

    3.2 使用简单

    如果是完全映射的，使用起来肯定没有反射简单。用类似 BeanUtils 这些工具一条语句就搞定了。但是，如果需要进行特殊的匹配（特殊类型转换，多对一转换等），其相对来说也是比较简单的。
    基本上，使用的时候，只需要声明一个接口，接口下写对应的方法，就可以使用了。当然，如果有特殊情况，是需要额外处理的。

    3.3 代码独立

    生成的代码是对立的，没有运行时的依赖。

    3.4 易于 debug

    在生成的代码中，可以轻易的进行 debug。

    4、MapStruct使用案例

    4.1 属性名称相同

    在实现类的时候，如果属性名称相同，则会进行对应的转化。通过此种方式，可以快速的编写出转换的方法。（入门案例）

    4.2 属性名不相同

    属性名不相同，在需要进行互相转化的时候，则可以通过@Mapping 注解来进行转化。 ```java @Data public class UserDto implements Serializable { private Integer id; private String name; private String address; private Date birth; private String password; }

@Data public class User { private Integer id; private String name; private String address; private Date birth; private String pwd; }

@Mapper public interface UserMapper { //单个属性 //@Mapping(source = “pwd”,target = “password”) //多个属性 @Mappings({ @Mapping(source = “pwd”,target = “password”) }) UserDto userToUserDto(User user); }

  2. - source 需要转换的对接，通常是入参
  3. - target 转换的对接，通常是出参
  4. - ignore 忽略，默认false不忽略，需要忽略设置为true
  5. - defaultValue 默认值
  6. - expressions 可以通过表达式来构造一些简单的转化关系。虽然设计的时候想兼容很多语言，不过目前只能写Java代码。
  7. ```java
  8. @Mappings({
  9.             @Mapping(source = "birthdate", target = "birth"),//属性名不一致映射
  10.             @Mapping(target = "birthformat", expression = "java(org.apache.commons.lang3.time.DateFormatUtils.format(person.getBirthdate(),\"yyyy-MM-dd HH:mm:ss\"))"),//自定义属性通过java代码映射
  11.     })
  12. public PersonVo PersonToPersonVo(Person person);

这里用到演示了如何使用TimeAndFormat对time和format操作，这里必须要指定需要使用的Java类的完整包名，不然编译的时候不知道使用哪个Java类，会报错。

  1. @Test
  2. public void userPoToUserDto() {
  3.     User user =new User();
  4.     user.setId(1);
  5.     user.setName("myx");
  6.     user.setAddress("河北沧州");
  7.     user.setBirth(new Date());
  8.     user.setPwd("123456");
  9.     UserMapper mapper = Mappers.getMapper(UserMapper.class);
  10.     UserDto userDto = mapper.userToUserDto(user);
  11.     System.out.println(userDto);
  12. }

2021-09-04-13-56-49-854037.png

4.3 转换非基础类型属性

如果subUser与subUserDto字段名称相同直接配置即可完成(对象类型，包括list)

  1. @Data
  2. public class UserDto implements Serializable {
  3.     private Integer id;
  4.     private String name;
  5.     private String address;
  6.     private Date birth;
  7.     private String password;
  8.     private List<SubUserDto> subUserDto;
  9. }
  11. @Data
  12. public class User {
  13.     private Integer id;
  14.     private String name;
  15.     private String address;
  16.     private Date birth;
  17.     private String pwd;
  18.     private List<SubUser> subUser;
  19. }
  21. @Mappings({
  22.         @Mapping(source = "pwd",target = "password"),
  23.         @Mapping(source = "subUser", target = "subUserDto")
  24. })
  25. UserDto userToUserDto(User user);

4.4 Mapper 中使用自定义的转换

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

  1. @Data
  2. public class UserDto implements Serializable {
  3.     private Integer id;
  4.     private String name;
  5.     private String address;
  6.     private Date birth;
  7.     private String password;
  8.     private SubUserDto subUserDto;
  9. }
  11. @Data
  12. public class SubUserDto {
  13.     private Boolean result;
  14.     private String name;
  15. }
  17. @Data
  18. public class User {
  19.     private Integer id;
  20.     private String name;
  21.     private String address;
  22.     private Date birth;
  23.     private String pwd;
  24.     private SubUser subUser;
  25. }
  27. @Data
  28. public class SubUser {
  29.     private Integer deleted;
  30.     private String name;
  31. }
  33. @Mapper
  34. public interface UserMapper {
  35.     @Mappings({
  36.             @Mapping(source = "pwd",target = "password"),
  37.             @Mapping(source = "subUser", target = "subUserDto")
  38.     })
  39.     UserDto userToUserDto(User user);
  41.     default SubUserDto subSource2subTarget(SubUser subUser) {
  42.         if (subUser == null) {
  43.             return null;
  44.         }
  45.         SubUserDto subUserDto = new SubUserDto();
  46.         subUserDto.setResult(!subUser.getDeleted().equals(0));
  47.         subUserDto.setName(subUser.getName()==null?"":subUser.getName());
  48.         return subUserDto;
  49.     }
  50. }

只能存在一个default修饰的方法

  1. @Test
  2. public void userPoToUserDto() {
  3.     User user =new User();
  4.     user.setId(1);
  5.     user.setName("myx");
  6.     user.setAddress("河北沧州");
  7.     user.setBirth(new Date());
  8.     user.setPwd("123456");
  9.     SubUser subUser =new SubUser();
  10.     subUser.setDeleted(0);
  11.     subUser.setName("rkw");
  12.     user.setSubUser(subUser);
  13.     UserMapper mapper = Mappers.getMapper(UserMapper.class);
  14.     UserDto userDto = mapper.userToUserDto(user);
  15.     System.out.println(userDto);
  16. }

2021-09-04-13-56-49-993083.png

4.5 多转一

在实际的业务中少不了将多个对象转换成一个的场景。MapStruct 当然也支持多转一的操作。

  1. @Data
  2. public class SubUser {
  3.     private Integer deleted;
  4.     private String name;
  5. }
  7. @Data
  8. public class User {
  9.     private Integer id;
  10.     private String name;
  11.     private String address;
  12.     private Date birth;
  13.     private String pwd;
  14. }
  16. @Mapper
  17. public interface UserMapper {
  18.     @Mappings({
  19.             @Mapping(source = "user.pwd",target = "password"),
  20.             @Mapping(source = "subUser.name", target = "name")
  21.     })
  22.     NewUserDto userToUserDto(User user,SubUser subUser);
  23. }
  25. @Test
  26. public void userPoToUserDto() {
  27.     User user =new User();
  28.     user.setId(1);
  29.     user.setName("myx");
  30.     user.setAddress("河北沧州");
  31.     user.setBirth(new Date());
  32.     user.setPwd("123456");
  33.     SubUser subUser =new SubUser();
  34.     subUser.setDeleted(0);
  35.     subUser.setName("rkw");
  36.     UserMapper mapper = Mappers.getMapper(UserMapper.class);
  37.     NewUserDto userDto = mapper.userToUserDto(user,subUser);
  38.     System.out.println(userDto);
  39. }

2021-09-04-13-56-50-169309.png

4.5.1 遵循原则

  • 当多个对象中， 有其中一个为 null， 则会直接返回 null
  • 如一对一转换一样， 属性通过名字来自动匹配。因此， 名称和类型相同的不需要进行特殊处理
  • 当多个原对象中，有相同名字的属性时，需要通过 @Mapping 注解来具体的指定， 以免出现歧义（不指定会报错）。如上面的 name

属性也可以直接从传入的参数来赋值

  1. @Mapping(source = "person.description", target = "description")
  2. @Mapping(source = "name", target = "name")
  3. DeliveryAddress personAndAddressToDeliveryAddressDto(Person person, String name);

4.6 更新 Bean 对象

有时候，不是想返回一个新的 Bean 对象，而是希望更新传入对象的一些属性。这个在实际的时候也会经常使用到。

  1. @Mapper
  2. public interface UserMapper {
  4.     NewUserDto userToNewUserDto(User user);
  6.     /**
  7.      * 更新， 注意注解 @MappingTarget
  8.      * 注解 @MappingTarget后面跟的对象会被更新。
  9.      */
  10.     void updateDeliveryAddressFromAddress(SubUser subUser,@MappingTarget NewUserDto newUserDto);
  11. }
  13. @Test
  14. public void userPoToUserDto() {
  15.     User user =new User();
  16.     user.setId(1);
  17.     user.setName("myx");
  18.     user.setAddress("河北沧州");
  19.     user.setBirth(new Date());
  20.     SubUser subUser =new SubUser();
  21.     subUser.setDeleted(0);
  22.     subUser.setName("rkw");
  23.     UserMapper mapper = Mappers.getMapper(UserMapper.class);
  24.     NewUserDto userDto = mapper.userToNewUserDto(user);
  25.     mapper.updateDeliveryAddressFromAddress(subUser,userDto);
  26.     System.out.println(userDto);
  27. }

4.7 map映射

  1. @MapMapping(valueDateFormat ="yyyy-MM-dd HH:mm:ss")
  2. public Map<String ,String> DateMapToStringMap(Map<String,Date> sourceMap);
  4. @Test
  5. public void mapMappingTest(){
  6.     Map<String,Date> map=new HashMap<>();
  7.     map.put("key1",new Date());
  8.     map.put("key2",new Date(new Date().getTime()+9800000));
  9.     Map<String, String> stringObjectMap = TestMapper.MAPPER.DateMapToStringMap(map);
  10. }

4.8 多级嵌套

只需要在mapper接口中定义相关的类型转换方法即可，list类型也适用

4.8.1 方式1

  1. @Data
  2. public class User {
  3.     private Integer id;
  4.     private String name;
  5.     private String address;
  6.     private Date birth;
  7.     private Boolean isDisable;
  8.     private List<SubUser> user;
  9. }
  11. @Data
  12. public class SubUser {
  13.     private Integer deleted;
  14.     private String name;
  15.     private List<SubSubUser> subUser;
  16. }
  17. @Data
  18. public class SubSubUser {
  19.     private String aaa;
  20.     private String ccc;
  21. }
  23. @Data
  24. public class UserDto implements Serializable {
  25.     private Integer id;
  26.     private String name;
  27.     private String address;
  28.     private Date birth;
  29.     private String isDisable;
  30.     private List<SubUserDto> user;
  31. }
  32. @Data
  33. public class SubUserDto {
  34.     private Integer deleted;
  35.     private String name;
  36.     private List<SubSubUserDto> subUser;
  37. }
  38. @Data
  39. public class SubSubUserDto {
  40.     private String aaa;
  41.     private  String bbb;
  42. }
  44. @Mapper
  45. public interface UserMapper {
  47.     UserDto userToNewUserDto(User user);
  49.     //子集字段相同方法不用编写会自动生成
  51.     //孙子集字段不相同(list会自动读取此方法生成list)
  52.     @Mapping(source = "ccc",target = "bbb")
  53.     SubSubUserDto bbb(SubSubUser subSubUser);
  55. }

4.8.2 方式2

通过uses配置类型转换

  1. @Mapper(uses = {TestMapper.class})
  2. public interface UserMapper {
  3.     UserDto userToNewUserDto(User user);
  4. }
  6. @Mapper
  7. public interface TestMapper {
  8.     @Mapping(source = "ccc",target = "bbb")
  9.     SubSubUserDto bbb(SubSubUser subSubUser);
  10. }

5、获取 mapper

5.1 通过 Mapper 工厂获取

都是通过 Mappers.getMapper(xxx.class) 的方式来进行对应 Mapper 的获取。此种方法为通过 Mapper 工厂获取。
如果是此种方法，约定俗成的是在接口内定义一个接口本身的实例 INSTANCE， 以方便获取对应的实例。

  1. @Mapper
  2. public interface SourceMapper {
  4.     SourceMapper INSTANCE = Mappers.getMapper(SourceMapper.class);
  6.     // ......
  7. }

这样在调用的时候，就不需要在重复的去实例化对象了。类似下面

  1. Target target = SourceMapper.INSTANCE.source2target(source);

5.2 使用依赖注入

对于 Web 开发，依赖注入应该很熟悉。MapSturct 也支持使用依赖注入，同时也推荐使用依赖注入。
2021-09-04-13-56-50-326334.png

  1. @Mapper(componentModel = "spring")

5.3 依赖注入策略

可以选择是通过构造方法或者属性注入，默认是属性注入。

  1. public enum InjectionStrategy {
  3.     /** Annotations are written on the field **/
  4.     FIELD,
  6.     /** Annotations are written on the constructor **/
  7.     CONSTRUCTOR
  8. }

类似如此使用

  1. @Mapper(componentModel = "cdi" injectionStrategy = InjectionStrategy.CONSTRUCTOR)

5.4 自定义类型转换

有时候，在对象转换的时候可能会出现这样一个问题，就是源对象中的类型是Boolean类型，而目标对象类型是String类型，这种情况可以通过@Mapper的uses属性来实现：

  1. @Data
  2. public class User {
  3.     private Integer id;
  4.     private String name;
  5.     private String address;
  6.     private Date birth;
  7.     private Boolean isDisable;
  8. }
  10. @Data
  11. public class UserDto implements Serializable {
  12.     private Integer id;
  13.     private String name;
  14.     private String address;
  15.     private Date birth;
  16.     private String isDisable;
  17. }
  19. @Mapper(uses = {BooleanStrFormat.class})
  20. public interface UserMapper {
  21.     UserDto userToNewUserDto(User user);
  22. }
  24. public class BooleanStrFormat {
  25.     public String toStr(Boolean isDisable) {
  26.         if (isDisable) {
  27.             return "Y";
  28.         } else {
  29.             return "N";
  30.         }
  31.     }
  32.     public Boolean toBoolean(String str) {
  33.         if (str.equals("Y")) {
  34.             return true;
  35.         } else {
  36.             return false;
  37.         }
  38.     }
  39. }

要注意的是，如果使用了例如像spring这样的环境，Mapper引入uses类实例的方式将是自动注入，那么这个类也应该纳入Spring容器

  1. @Test
  2. public void userPoToUserDto() {
  3.     User user =new User();
  4.     user.setId(1);
  5.     user.setName("myx");
  6.     user.setAddress("河北沧州");
  7.     user.setBirth(new Date());
  8.     user.setIsDisable(true);
  9.     SubUser subUser =new SubUser();
  10.     subUser.setDeleted(0);
  11.     subUser.setName("rkw");
  12.     UserMapper mapper = Mappers.getMapper(UserMapper.class);
  13.     UserDto userDto = mapper.userToNewUserDto(user);
  14.     System.out.println(userDto);
  15. }