Java MapStruct
官网地址：https://mapstruct.org/
pom 配置：

  1. <properties>
  2.   <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  3.   <maven.compiler.source>1.8</maven.compiler.source>
  4.   <maven.compiler.target>1.8</maven.compiler.target>
  5.   <org.mapstruct.version>1.4.1.Final</org.mapstruct.version>
  6.   <org.projectlombok.version>1.18.12</org.projectlombok.version>
  7. </properties>
  9. <dependencies>
  10.   <dependency>
  11.     <groupId>org.mapstruct</groupId>
  12.     <artifactId>mapstruct</artifactId>
  13.     <version>${org.mapstruct.version}</version>
  14.   </dependency>
  16.   <!-- lombok dependencies should not end up on classpath -->
  17.   <dependency>
  18.     <groupId>org.projectlombok</groupId>
  19.     <artifactId>lombok</artifactId>
  20.     <version>${org.projectlombok.version}</version>
  21.     <scope>provided</scope>
  22.   </dependency>
  24.   <!-- idea 2018.1.1 之前的版本需要添加下面的配置，后期的版本就不需要了，可以注释掉，
  25. 这里用的2019.3 -->
  26.   <dependency>
  27.     <groupId>org.mapstruct</groupId>
  28.     <artifactId>mapstruct-processor</artifactId>
  29.     <version>${org.mapstruct.version}</version>
  30.     <scope>provided</scope>
  31.   </dependency>
  33. </dependencies>
  35. <build>
  36.   <plugins>
  37.     <plugin>
  38.       <groupId>org.apache.maven.plugins</groupId>
  39.       <artifactId>maven-compiler-plugin</artifactId>
  40.       <version>3.8.1</version>
  41.       <configuration>
  42.         <source>1.8</source>
  43.         <target>1.8</target>
  44.         <annotationProcessorPaths>
  45.           <path>
  46.             <groupId>org.projectlombok</groupId>
  47.             <artifactId>lombok</artifactId>
  48.             <version>${org.projectlombok.version}</version>
  49.           </path>
  50.           <path>
  51.             <groupId>org.mapstruct</groupId>
  52.             <artifactId>mapstruct-processor</artifactId>
  53.             <version>${org.mapstruct.version}</version>
  54.           </path>
  55.         </annotationProcessorPaths>
  56.       </configuration>
  57.     </plugin>
  58.   </plugins>
  59. </build>

关于lombok和mapstruct的版本兼容问题，maven插件要使用3.6.0版本以上、lombok使用1.16.16版本以上，另外编译的lombok mapstruct的插件不要忘了。否则会出现下面的错误：No property named “aaa” exists in source parameter(s). Did you mean “null”?
这种异常就是lombok编译异常导致缺少get setter方法造成的。还有就是缺少构造函数也会抛异常。

  1. @Data
  2. @Builder
  3. @AllArgsConstructor
  4. @NoArgsConstructor
  5. public class Student {
  7.     private String name;
  8.     private int age;
  9.     private GenderEnum gender;
  10.     private Double height;
  11.     private Date birthday;
  13. }
  14. public enum GenderEnum {
  15.     Male("1", "男"),
  16.     Female("0", "女");
  18.     private String code;
  19.     private String name;
  21.     public String getCode() {
  22.         return this.code;
  23.     }
  25.     public String getName() {
  26.         return this.name;
  27.     }
  29.     GenderEnum(String code, String name) {
  30.         this.code = code;
  31.         this.name = name;
  32.     }
  33. }
  34. @Data
  35. @Builder
  36. @AllArgsConstructor
  37. @NoArgsConstructor
  38. public class StudentVO {
  39.     private String name;
  40.     private int age;
  41.     private String gender;
  42.     private Double height;
  43.     private String birthday;
  44. }
  45. @Mapper
  46. public interface StudentMapper {
  48.     StudentMapper INSTANCE = Mappers.getMapper(StudentMapper.class);
  50.     @Mapping(source = "gender.name", target = "gender")
  51.     @Mapping(source = "birthday", target = "birthday", dateFormat = "yyyy-MM-dd HH:mm:ss")
  52.     StudentVO student2StudentVO(Student student);
  54. }

实体类是开发过程少不了的，就算是用工具生成肯定也是要有的，需要手写的部分就是这个Mapper的接口，编译完成后会自动生成相应的实现类
2021-09-18-12-19-39-501373.png
然后就可以直接用mapper进行实体的转换了

  1. public class Test {
  3.     public static void main(String[] args) {
  5.         Student student = Student.builder().name("小明").age(6).gender(GenderEnum.Male).height(121.1).birthday(new Date()).build();
  6.         System.out.println(student);
  7.         //这行代码便是实际要用的代码
  8.         StudentVO studentVO = StudentMapper.INSTANCE.student2StudentVO(student);
  9.         System.out.println(studentVO);
  11.     }
  13. }

2021-09-18-12-19-44-402370.png
mapper可以进行字段映射，改变字段类型，指定格式化的方式，包括一些日期的默认处理。
可以手动指定格式化的方法：

  1. @Mapper
  2. public interface StudentMapper {
  4.     StudentMapper INSTANCE = Mappers.getMapper(StudentMapper.class);
  6.     @Mapping(source = "gender", target = "gender")
  7.     @Mapping(source = "birthday", target = "birthday", dateFormat = "yyyy-MM-dd HH:mm:ss")
  8.     StudentVO student2StudentVO(Student student);
  10.     default String getGenderName(GenderEnum gender) {
  11.         return gender.getName();
  12.     }
  14. }

上面只是最简单的实体映射处理，下面介绍一些高级用法

1、List 转换

属性映射基于上面的mapping配置

  1. @Mapper
  2. public interface StudentMapper {
  4.     StudentMapper INSTANCE = Mappers.getMapper(StudentMapper.class);
  6.     @Mapping(source = "gender.name", target = "gender")
  7.     @Mapping(source = "birthday", target = "birthday", dateFormat = "yyyy-MM-dd HH:mm:ss")
  8.     StudentVO student2StudentVO(Student student);
  11.     List<StudentVO> students2StudentVOs(List<Student> studentList);
  13. }
  15. public static void main(String[] args) {
  17.     Student student = Student.builder().name("小明").age(6).gender(GenderEnum.Male).height(121.1).birthday(new Date()).build();
  19.     List<Student> list = new ArrayList<>();
  20.     list.add(student);
  21.     List<StudentVO> result = StudentMapper.INSTANCE.students2StudentVOs(list);
  22.     System.out.println(result);
  23. }

2021-09-18-12-19-49-492167.png

2、多对象转换到一个对象

  1. @Data
  2. @Builder
  3. @AllArgsConstructor
  4. @NoArgsConstructor
  5. public class Student {
  7.     private String name;
  8.     private int age;
  9.     private GenderEnum gender;
  10.     private Double height;
  11.     private Date birthday;
  13. }
  15. @Data
  16. @AllArgsConstructor
  17. @Builder
  18. @NoArgsConstructor
  19. public class Course {
  21.     private String courseName;
  22.     private int sortNo;
  23.     private long id;
  25. }
  27. @Data
  28. @Builder
  29. @AllArgsConstructor
  30. @NoArgsConstructor
  31. public class StudentVO {
  32.     private String name;
  33.     private int age;
  34.     private String gender;
  35.     private Double height;
  36.     private String birthday;
  37.     private String course;
  38. }
  40. @Mapper
  41. public interface StudentMapper {
  43.     StudentMapper INSTANCE = Mappers.getMapper(StudentMapper.class);
  45.     @Mapping(source = "student.gender.name", target = "gender")
  46.     @Mapping(source = "student.birthday", target = "birthday", dateFormat = "yyyy-MM-dd HH:mm:ss")
  47.     @Mapping(source = "course.courseName", target = "course")
  48.     StudentVO studentAndCourse2StudentVO(Student student, Course course);
  50. }
  52. public class Test {
  54.     public static void main(String[] args) {
  56.         Student student = Student.builder().name("小明").age(6).gender(GenderEnum.Male).height(121.1).birthday(new Date()).build();
  57.         Course course = Course.builder().id(1L).courseName("语文").build();
  59.         StudentVO studentVO = StudentMapper.INSTANCE.studentAndCourse2StudentVO(student, course);
  60.         System.out.println(studentVO);
  61.     }
  63. }

2021-09-18-12-20-59-717165.png

3、默认值

  1. @Mapper
  2. public interface StudentMapper {
  4.     StudentMapper INSTANCE = Mappers.getMapper(StudentMapper.class);
  6.     @Mapping(source = "student.gender.name", target = "gender")
  7.     @Mapping(source = "student.birthday", target = "birthday", dateFormat = "yyyy-MM-dd HH:mm:ss")
  8.     @Mapping(source = "course.courseName", target = "course")
  9.     @Mapping(target = "name", source = "student.name", defaultValue = "张三")
  10.     StudentVO studentAndCourse2StudentVO(Student student, Course course);
  12. }

2021-09-18-12-20-59-886146.png

4、转换基类

准备工作

使用常见的 User 类以及对应 UserDto 对象来演示。

  1. @Data
  2. @Accessors(chain = true)
  3. public class User {
  4.     private Long id;
  5.     private String username;
  6.     private String password;
  7.     private Integer sex;
  8.     private LocalDate birthday;
  9.     private LocalDateTime createTime;
  10.     private String config;
  11.     private String test;
  12. }
  14. @Data
  15. @Accessors(chain = true)
  16. public class UserVo {
  17.     private Long id;
  18.     private String username;
  19.     private String password;
  20.     private Integer gender;
  21.     private LocalDate birthday;
  22.     private String createTime;
  23.     private List<UserConfig> config;
  24.     private String test;
  25.     @Data
  26.     public static class UserConfig {
  27.         private String field1;
  28.         private Integer field2;
  29.     }
  30. }

注意观察这两个类的区别。
因为项目中的对象转换操作基本都一样，因此抽取除了一个转换基类，不同对象如果只是简单转换可以直接继承该基类，而无需覆写基类任何方法，即只需要一个空类即可。如果子类覆写了基类的方法，则基类上的 @Mapping 会失效。

  1. @MapperConfig
  2. public interface BaseMapping<SOURCE, TARGET> {
  4.     /**
  5.      * 映射同名属性
  6.      */
  7.     @Mapping(target = "createTime", dateFormat = "yyyy-MM-dd HH:mm:ss")
  8.     TARGET sourceToTarget(SOURCE var1);
  10.     /**
  11.      * 反向，映射同名属性
  12.      */
  13.     @InheritInverseConfiguration(name = "sourceToTarget")
  14.     SOURCE targetToSource(TARGET var1);
  16.     /**
  17.      * 映射同名属性，集合形式
  18.      */
  19.     @InheritConfiguration(name = "sourceToTarget")
  20.     List<TARGET> sourceToTarget(List<SOURCE> var1);
  22.     /**
  23.      * 反向，映射同名属性，集合形式
  24.      */
  25.     @InheritConfiguration(name = "targetToSource")
  26.     List<SOURCE> targetToSource(List<TARGET> var1);
  28.     /**
  29.      * 映射同名属性，集合流形式
  30.      */
  31.     List<TARGET> sourceToTarget(Stream<SOURCE> stream);
  33.     /**
  34.      * 反向，映射同名属性，集合流形式
  35.      */
  36.     List<SOURCE> targetToSource(Stream<TARGET> stream);
  37. }

实现 User 与 UserVo 对象的转换器

  1. import org.mapstruct.Mapper;
  2. import org.mapstruct.Mapping;
  4. @Mapper(componentModel = "spring")
  5. public interface UserMapping extends BaseMapping<User, UserVo> {
  7.     @Mapping(target = "gender", source = "sex")
  8.     @Mapping(target = "createTime", dateFormat = "yyyy-MM-dd HH:mm:ss")
  9.     @Override
  10.     UserVo sourceToTarget(User var1);
  12.     @Mapping(target = "sex", source = "gender")
  13.     @Mapping(target = "password", ignore = true)
  14.     @Mapping(target = "createTime", dateFormat = "yyyy-MM-dd HH:mm:ss")
  15.     @Override
  16.     User targetToSource(UserVo var1);
  18.     default List<UserConfig> strConfigToListUserConfig(String config) {
  19.         return JSON.parseArray(config, UserConfig.class);
  20.     }
  22.     default String listUserConfigToStrConfig(List<UserConfig> list) {
  23.         return JSON.toJSONString(list);
  24.     }
  25. }

这里使用的是 Spring 的方式，@Mapper 注解的 componentModel 属性值为 spring，不过应该大多数都用的此模式进行开发。
@Mapping用于配置对象的映射关系，示例中 User 对象性别属性名为 sex，而UserVo对象性别属性名为gender，因此需要配置 target 与 source 属性。
password 字段不应该返回到前台，可以采取两种方式不进行转换，第一种就是在vo对象中不出现password字段，第二种就是在@Mapping中设置该字段 ignore = true。
MapStruct 提供了时间格式化的属性 dataFormat，支持Date、LocalDate、LocalDateTime等时间类型与String的转换。示例中birthday 属性为 LocalDate 类型，可以无需指定dataFormat自动完成转换，而LocalDateTime类型默认使用的是ISO格式时间，在国内往往不符合需求，因此需要手动指定一下 dataFormat。

5、自定义属性类型转换方法

一般常用的类型字段转换 MapStruct都能完成，但是有一些是自定义的对象类型，MapStruct就不能进行字段转换，这就需要编写对应的类型转换方法，这里使用的是JDK8，支持接口中的默认方法，可以直接在转换器中添加自定义类型转换方法。
示例中User对象的config属性是一个JSON字符串，UserVo对象中是List类型的，这需要实现JSON字符串与对象的互转。

  1. default List<UserConfig> strConfigToListUserConfig(String config) {
  2.   return JSON.parseArray(config, UserConfig.class);
  3. }
  5. default String listUserConfigToStrConfig(List<UserConfig> list) {
  6.   return JSON.toJSONString(list);
  7. }

如果是 JDK8以下的，不支持默认方法，可以另外定义一个 转换器，然后再当前转换器的 @Mapper 中通过 uses = XXX.class 进行引用。
定义好方法之后，MapStruct当匹配到合适类型的字段时，会调用自定义的转换方法进行转换。

单元测试

  1. @Slf4j
  2. @RunWith(SpringRunner.class)
  3. @SpringBootTest
  4. public class MapStructTest {
  6.     @Resource
  7.     private UserMapping userMapping;
  9.     @Test
  10.     public void tetDomain2DTO() {
  11.         User user = new User()
  12.             .setId(1L)
  13.             .setUsername("zhangsan")
  14.             .setSex(1)
  15.             .setPassword("abc123")
  16.             .setCreateTime(LocalDateTime.now())
  17.             .setBirthday(LocalDate.of(1999, 9, 27))
  18.             .setConfig("[{\"field1\":\"Test Field1\",\"field2\":500}]");
  19.         UserVo userVo = userMapping.sourceToTarget(user);
  20.         log.info("User: {}", user);
  22.         log.info("UserVo: {}", userVo);
  24.     }
  26.     @Test
  27.     public void testDTO2Domain() {
  28.         UserConfig userConfig = new UserConfig();
  29.         userConfig.setField1("Test Field1");
  30.         userConfig.setField2(500);
  32.         UserVo userVo = new UserVo()
  33.             .setId(1L)
  34.             .setUsername("zhangsan")
  35.             .setGender(2)
  36.             .setCreateTime("2020-01-18 15:32:54")
  37.             .setBirthday(LocalDate.of(1999, 9, 27))
  38.             .setConfig(Collections.singletonList(userConfig));
  39.         User user = userMapping.targetToSource(userVo);
  40.         log.info("UserVo: {}", userVo);
  41.         log.info("User: {}", user);
  42.     }
  43. }

6、常见问题

当两个对象属性不一致时，比如User对象中某个字段不存在与UserVo当中时，在编译时会有警告提示，可以在@Mapping中配置 ignore = true，当字段较多时，可以直接在@Mapper中设置unmappedTargetPolicy属性或者unmappedSourcePolicy属性为 ReportingPolicy.IGNORE即可。
如果项目中也同时使用到了 Lombok，一定要注意 Lombok的版本要等于或者高于1.18.10，否则会有编译不通过的情况发生。