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

雨点打透心脏的1/2处 2024-02-21 11:55 8阅读 0赞

#### 文章目录 ####

*  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 进阶操作
     *   *  1.依赖注入
         *  2.默认值
         *  3.添加表达式
         *  4.添加自定义方法
         *  5.创建自定义映射器
         *   *  @BeforeMapping 和 @AfterMapping
         *  6.映射异常处理
         *  7.映射配置
         *   *  7.1 继承配置
             *  7.2 继承逆向配置
 *  6.对象与Map的转换
 *   *  6.1 Map转对象
     *  6.2 对象转Map
 *  6.总结

## 1.背景 ##

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

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

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

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

## 2.mapstruct简介 ##

![在这里插入图片描述][1707d094f6c14fb7b007a4a422059efe.png_pic_center]

**mapstruct** 是一种**实体类 映射框架**  ，能够通过**Java注解** 将一个实体类的属性安全地赋值给另一个实体类。它基于**约定优于配置方法** 极大地简化了 Java bean 类型之间映射的实现，有了mapstruct，只需要定义一个映射器接口，声明需要映射的方法，在**编译过程中** ，mapstruct会自动生成该接口的实现类，实现将源对象映射到目标对象的效果。

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

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

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

## 3.mapstruct与其他映射对比 ##

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

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

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

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

## 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程序编译的流程：  
![在这里插入图片描述][caa40d7e3bdb425585ff26d274f10c4a.png_pic_center]

上图中Java源码到class文件的过程其实是一个比较复杂的过程。其中的经过可以用下图描述：  
![在这里插入图片描述][3a987cb218c6422c894843f4dc1a784e.png_pic_center]

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

*  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;
    }

![在这里插入图片描述][90a99f71f99946b48489756c31baabcb.png_pic_center]

创建对象转换器（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());
    	}
    }

![在这里插入图片描述][bd327a84928e4d37843a7d83dbc0320b.png_pic_center]

可以看到测试通过

编译之后，MapStruct注解处理器插件会识别出DoctorMapper接口并为其生成一个实现类。  
，在Mapper上就可以看见其具体的实现  
![在这里插入图片描述][24c0365a86d4480db784cb47003a9525.png_pic_center]

![在这里插入图片描述][c8a64790bb3449349ddd7369c85d5410.png_pic_center]

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

#### 2.UserA和UserB字段不同 ####

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

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

和UserA相比发现name字段其实是无法映射的  
![在这里插入图片描述][981ef49fbb4d4095896f161a9eda5628.png_pic_center]

只需要在Mapper里加入toUserC的方法即可

UserC toUserC(UserA userA);

![在这里插入图片描述][c461bfbed2644fc19ebf8b7719fb4587.png_pic_center]

进行一下测试

@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());
    	}

![在这里插入图片描述][98328102266c454e9447a3d1453bbaa9.png_pic_center]

可以发现UserC的name并没有转换成功，原因就是UserA中的name无法和UserBC中的userName字段进行映射

怎么办呢？

方法也很简单

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

只需要我们手动去实现映射即可，再次允许Test2方法进行测试，可以发现测试可以通过  
![在这里插入图片描述][e949d0cdc3564b46b0306c4666ce0a1c.png_pic_center]

上面我们已经提到了@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));
        }

![在这里插入图片描述][3bf16eb731c8444d84aa10017e57aab2.png_pic_center]

#### 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));
        }

![在这里插入图片描述][06b1a3c50a3a459389f6213a5cf16cc4.png_pic_center]

#### 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官方文档][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));
        }

![在这里插入图片描述][b735db1c76a34974a79aed37035c42f8.png_pic_center]

除此之外，对于数字的转换，也可以使用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);
        }

![在这里插入图片描述][680c0cfc813a4d11afeb723e53c5c67e.png_pic_center]

但是，如果你要将很多值转换为一个更一般的值，这种方式就有些不切实际了。其实我们不必手动分配每一个值，只需要让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));
        }

![在这里插入图片描述][19d3df839b1e48b1b28e073bea8f6ac9.png_pic_center]

可以发现字段名称不一致的均未转换，这个时候我们把实体和实体之间的字段映射加进去

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

再次运行刚刚的测试用例，可以发现所有的字段映射成功  
![在这里插入图片描述][2844fafc04234787ae09901d6b444671.png_pic_center]

##### 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);
    }

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

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

##### 集合映射策略 #####

@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方法

编译之后的实现类：  
![在这里插入图片描述][8fe0cad0ecd74d048a914674076bc5ec.png_pic_center]

可以看到，在默认情况下采用的策略是**ACCESSOR\_ONLY** ，使用setter方法setCourseDtoList()向UserDto对象中写入列表数据。

相对的，如果使用**ADDER\_PREFERRED**  作为映射策略：

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

此时，会使用adder方法逐个将转换后的子类型DTO对象加入父类型的集合字段中。  
![在这里插入图片描述][2cd85c1eec81482ebe1ddcc942d857ea.png_pic_center]

如果目标DTO中既没有setter方法也没有adder方法，会先通过getter方法获取子类型集合，再调用集合的对应接口添加子类型对象。

### 5.3 进阶操作 ###

#### 1.依赖注入 ####

到目前为止，我们一直在通过getMapper()方法访问生成的映射器：  
![在这里插入图片描述][b98d3ecfecce420ca1d6aee1b746c420.png_pic_center]

但是，如果你使用的是Spring，只需要简单修改映射器配置，就可以像常规依赖项一样注入映射器。

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

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

此时，生成的UserMapperImpl中会带有 @Component 注解：  
![在这里插入图片描述][7dda17d74030463a936501d1877a5ea7.png_pic_center]

只要被标记为@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 {
        }

#### 2.默认值 ####

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

@Mapper(componentModel = "spring")
    public interface UserMapper {
        
        @Mappings({
        
                @Mapping(target = "id",constant = "-1"),
                @Mapping(source = "courseList", target = "courseDtoList"),
                @Mapping(source = "birthdate", target = "birthdate", dateFormat = "dd/MMM/yyyy"),
                @Mapping(target = "name", defaultValue = "Information Not Available"),
        })
        UserDto toUserDto(UserA userA);
    }

如果**name不可用**，我们会替换为**"Information** **Not** **Available**"字符串，此外，我们将**id硬编码为**\-1**。**

![在这里插入图片描述][f425925984f5451dbeed145433555753.png_pic_center]

#### 3.添加表达式 ####

MapStruct甚至允许在**@Mapping注解中输入Java表达式**。你可以设置 **defaultExpression** （ **source** 取值为 **null时生效**）**，或者一个expression**（类似常量**，永久生效**）**。**

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

编译完成之后，可以发现：  
![在这里插入图片描述][dda1a932da69439594eafd983d3beab6.png_pic_center]

虽然已经转换成我们想要的样子，但是，会发现LocalDate没有被引入，在我们本地开发时，编译之后我们可以手动引入，但是编译成jar或者部署到服务器上的时候就无法手动去添加，此时我们可以事先在 @Mapper 中添加 imports = \{LocalDate.class\} 。  
![在这里插入图片描述][6fefd8e1aa5e4d76bf6fb28f86bb64e9.png_pic_center]

再次编译，就可以发现已经正常了

#### 4.添加自定义方法 ####

到目前为止，我们一直使用的策略是添加一个**“占位符”**方法**，并期望MapStruct能为我们实现它**。其实我们还可以向接口中添加自定义的**default方法**，也可以通过**default方法直接实现一个映射**。然后我们可以通过实例直接调用该方法**，没有任何问题**。

接下来我们创建一个UserCourseSummary类

@Data
    @Builder
    public class UserCourseSummary {
        
        private Integer userId;
        private String userName;
        private Integer courseCount;
        private List<String> courseNames;
        private Integer courseTime;
    }

在UserMapper中添加：

default UserCourseSummary toUserCourseSummary(UserA userA, Course course) {
        
            return UserCourseSummary.builder()
                    .userId(userA.getId())
                    .userName(userA.getName())
                    .courseCount(userA.getCourseList().size())
                    .courseNames(userA.getCourseList()
                            .stream()
                            .map(Course::getName)
                            .collect(Collectors.toList()))
                    .courseTime(course.getTime())
                    .build();
        }

后面我们则可以通过这个方法直接去映射UserCourseSummary

@Test
        void test10() {
        
            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);
            UserCourseSummary userCourseSummary = userMapper.toUserCourseSummary(userA, course);
            System.out.println(JSON.toJSONString(userCourseSummary));
        }

#### 5.创建自定义映射器 ####

前面我们一直是通过接口来设计映射器功能，其实我们也可以通过一个带**@Mapper** 的 **abstract** 类来实现一个映射器**。MapStruct也会为这个类创建一个实现**，类似于创建一个接口实现**。**

@Mapper(componentModel = "spring")
    public abstract class UserCustomMapper {
        
        public UserCourseSummary toUserCourseSummary(UserA userA, Course course) {
        
            return UserCourseSummary.builder()
                    .userId(userA.getId())
                    .userName(userA.getName())
                    .courseCount(userA.getCourseList().size())
                    .courseNames(userA.getCourseList()
                            .stream()
                            .map(Course::getName)
                            .collect(Collectors.toList()))
                    .courseTime(course.getTime())
                    .build();
        }
    }

##### @BeforeMapping 和 @AfterMapping #####

为了进一步控制和定制化，我们可以定义**@BeforeMapping** 和 **@AfterMapping**方法。显然，这两个方法是在每次映射之前和之后执行的。也就是说，在最终的实现代码中，会在两个对象真正映射之前和之后添加并执行这两个方法。

可以在UserCustomMapper中添加两个方法：

@BeforeMapping
        protected void validate(UserA user) {
        
            if(CollectionUtils.isEmpty(user.getCourseList())){
        
                user.setCourseList(new ArrayList<>());
            }
        }
    
        @AfterMapping
        protected void updateResult(@MappingTarget UserDto userDto) {
        
            userDto.setUserName(userDto.getUserName().toUpperCase());
            userDto.setDegree(userDto.getDegree().toUpperCase());
        }

并新增一个user->UserDto的映射

@Mapping(source = "userA.name", target = "userName")
        public abstract UserDto toDoctorDto(UserA userA);

编译之后：  
![在这里插入图片描述][d4d3a057fe024559a2b22d11cced101a.png_pic_center]

可以看到， validate() 方法会在 DoctorDto 对象实例化之前执行，而updateResult()方法会在映射结束之后执行。

#### 6.映射异常处理 ####

异常处理是不可避免的，应用程序随时会产生异常状态。MapStruct提供了对异常处理的支持，可以简化开发者的工作。

考虑这样一个场景，我们想在 User 映射为UserDto之前校验一下 User 的数据。我们新建一个独立的 Validator 类进行校验：

@Component
    public class Validator {
        
        public int validateId(int id) throws ValidationException {
        
            if(id == -1){
        
                throw new ValidationException("Invalid value in ID");
            }
            return id;
        }
    }

并修改userMapper

@Mapper(componentModel = "spring", uses = {
        Validator.class},imports = {
        LocalDate.class,})
    public interface UserMapper {
        
        @Mappings({
        
                @Mapping(target = "id", constant = "-1"),
                @Mapping(source = "courseList", target = "courseDtoList"),
                @Mapping(source = "birthdate", target = "birthdate", dateFormat = "dd/MMM/yyyy"),
                @Mapping(source = "name", target = "userName", defaultValue = "Information Not Available"),
        })
        UserDto toUserDto(UserA userA);
    
    }

再次重新编译：

@Generated(
        value = "org.mapstruct.ap.MappingProcessor",
        date = "2023-11-03T14:13:15+0800",
        comments = "version: 1.5.5.Final, compiler: javac, environment: Java 1.8.0_371 (Oracle Corporation)"
    )
    @Component
    public class UserMapperImpl implements UserMapper {
        
    
        @Autowired
        private Validator validator;
        @Override
        public UserDto toUserDto(UserA userA) {
        
            if ( userA == null ) {
        
                return null;
            }
    
            UserDto userDto = new UserDto();
    
            userDto.setCourseDtoList( courseListToCourseDtoList( userA.getCourseList() ) );
            userDto.setBirthdate( userA.getBirthdate() );
            if ( userA.getName() != null ) {
        
                userDto.setUserName( userA.getName() );
            }
            else {
        
                userDto.setUserName( "Information Not Available" );
            }
    
            try {
        
                userDto.setId( validator.validateId( -1 ) );
            }
            catch ( ValidationException e ) {
        
                throw new RuntimeException( e );
            }
    
            return userDto;
        }
    
    }

可以发现编译之后对于参数的校验也是十分的的优雅

**值得我们注意的是：如果映射前后的一对属性的类型与Validator中的方法出入参类型一致，那该字段映射时就会调用Validator中的方法，所以该方式请谨慎使用。**

#### 7.映射配置 ####

MapStruct为编写映射器方法提供了一些非常有用的配置。多数情况下，如果我们已经定义了两个类型之间的映射方法，当我们要添加相同类型之间的另一个映射方法时，我们往往会直接复制已有方法的映射配置。

其实我们不必手动复制这些注解，只需要简单的配置就可以创建一个相同/相似的映射方法。

##### 7.1 继承配置 #####

现在我们看一下这个场景：

> 我们创建了一个映射器，根据User对象的属性更新现有的UserDto对象的属性值

@Mapping(source = "userName", target = "name")
        void updateModel(UserA userA, @MappingTarget UserDto userDto);

当然我们还有另一中方式将UserDto转换为User：

@Mapping(source = "name", target = "userName", defaultValue = "Information Not Available")
        UserDto toUserDto(UserA userA);

这两个映射方法使用了相同的注解配置， source和 target都是相同的。其实我们可以使用@InheritConfiguration注释，从而避免这两个映射器方法的重复配置。

如果对一个方法添加 **@InheritConfiguration**  注解，MapStruct会检索其它的已配置方法，寻找可用于当前方法的注解配置。一般来说，这个注解都用于mapping方法后面的update方法，如下所示：

@InheritConfiguration
        void updateModel(UserA userA, @MappingTarget UserDto userDto);

同样，我们编译之后，可以看出两者实现一致，编译之后的代码过长，不在给出，自己可以build之后自行查看

##### 7.2 继承逆向配置 #####

还有另外一个类似的场景，就是编写映射函数将Model 转为 DTO，以及将 DTO 转为 Model。如下面的代码所示，我们必须在两个函数上添加相同的注释。

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

两个方法的配置不会是完全相同的，实际上，它们应该是相反的。将Model 转为 DTO，以及将 DTO 转为 Model——映射前后的字段相同，但是源属性字段与目标属性字段是相反的。

我们可以在第二个方法上使用**@InheritInverseConfiguration** 注解，避免写两遍映射配置：

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

编译之后：  
![在这里插入图片描述][ceed634e98cb4da9b4f5c4dc4e2f4a96.png_pic_center]

## 6.对象与Map的转换 ##

我们可以利用MapStruct工具轻松的实现对象之间的互转，也可以轻松实现Map到对象的转换

### 6.1 Map转对象 ###

如下所示：

UserA map2User(Map<String, String> map);

编译之后提示我们：  
![在这里插入图片描述][b0b3947cba2d400cb073e6e3fd577b05.png_pic_center]

这句话的意思是String类型无法转化为List类型的Course对象，此时，我们需要借助default方法，去将它转化一下：  
在UserMapper中添加：

UserA map2User(Map<String, String> map);
    
        default List<Course> str2List(String str) {
        
            return JSON.parseArray(str, Course.class);
        }

再次编译，可以看出：  
![在这里插入图片描述][0461174adb2e4023a0d3bc0b4ead0472.png_pic_center]

### 6.2 对象转Map ###

在UserMapper中添加

Map<String, String> user2String(UserA userA);

编译之后，发现：  
![在这里插入图片描述][544d647ea1cf402cb291973d0e3e2bfa.png_pic_center]

这个错误提示我们返回的对象不能是一个抽象类或接口，需要返回一个具体的实例化对象，那我们简单修改一下：

HashMap<String, String> user2String(UserA userA);

再次编译，发现虽然不报错，但是其具体的实现如下：  
![在这里插入图片描述][cea33670a1604a7c8d6904f835deeb7e.png_pic_center]

相当于什么都没做，就返回了一个空的HashMap，那我们该怎么去做，才能轻松优雅的实现对象转化为Map呢？

当然，实现的方式远远不止一种，下面我把常见的几种给大家写一下，自己看着选择一种即可

*  实现方式1：利用ObjectMapper实现

default Map<String, String> toMap1(Object object) {
        
            if (Objects.isNull(object)) {
        
                return new HashMap<>();
            }
            ObjectMapper objectMapper = new ObjectMapper();
            objectMapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
            objectMapper.registerModule(new JavaTimeModule());
            Map<String, String> targetMap = objectMapper.convertValue(object, HashMap.class);
            return targetMap;
    
        }

*  实现方式2：利用反射实现，像BeanUtils中的Map转换底层便是利用反射机制

default Map<String, String> toMap2(Object object) {
        
            Map<String, String> map = new HashMap<>(36);
            ReflectionUtils.doWithFields(object.getClass(), field -> {
        
                field.setAccessible(true);
                // 不处理自动化测试的插码字段
                if (field.isSynthetic()) {
        
                    return;
                }
                Object fieldValue = null;
                try {
        
                    fieldValue = field.get(object);
                } catch (IllegalAccessException e) {
        
                    throw new RuntimeException(e);
                }
                if (null != fieldValue) {
        
                    if (String.class.equals(field.getType())) {
        
                        map.put(field.getName(), fieldValue.toString());
                    } else {
        
                        map.put(field.getName(), JSON.toJSONString(fieldValue));
                    }
                }
            });
            return map;
        }

*  实现方式3：利用JSON序列化实现

default Map<String, String> toMap3(Object object) {
        
            if (Objects.isNull(object)) {
        
                return new HashMap<>();
            }
            String str = JSON.toJSONString(object);
            Map<String, String> map = JSON.parseObject(str, HashMap.class);
            return map;
        }

每种方式均已自测，大家可以自行尝试

## 6.总结 ##

在本文中，我们探讨了MapStruct——一个用于创建映射器类的库。从基本映射到自定义方法和自定义映射器，此外， 我们还介绍了MapStruct提供的一些高级操作选项，包括依赖注入，数据类型映射、枚举映射和表达式使用。

MapStruct提供了一个功能强大的集成插件，可减少开发人员编写模板代码的工作量，使创建映射器的过程变得简单快捷。

如果想知道更多关于该工具类的使用和操作，可移步：[MapStruct官方提供的参考指南][MapStruct 1]

[1707d094f6c14fb7b007a4a422059efe.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/08baf94843d942d3a3a1b479a1418eb4.png
[caa40d7e3bdb425585ff26d274f10c4a.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/cc6198b936fe4f4f8d7940762b2f473f.png
[3a987cb218c6422c894843f4dc1a784e.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/5ae2e923eaa448b2bf8bdbd7da3b7d27.png
[90a99f71f99946b48489756c31baabcb.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/9462361ded03478d8b04b38827f95918.png
[bd327a84928e4d37843a7d83dbc0320b.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/8f4aa3748f76473ba9c6d1b7bbbe5ccf.png
[24c0365a86d4480db784cb47003a9525.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/63bda7726da54f7fb70f210b72dab43f.png
[c8a64790bb3449349ddd7369c85d5410.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/86b87c8b035f48c888a01f005fe2a2d1.png
[981ef49fbb4d4095896f161a9eda5628.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/27009a950a814e8986c88eaacde0656c.png
[c461bfbed2644fc19ebf8b7719fb4587.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/43611cc23a2144a7b056aaa3cce468e4.png
[98328102266c454e9447a3d1453bbaa9.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/147ee9a5c48d402d82fc10d49acce150.png
[e949d0cdc3564b46b0306c4666ce0a1c.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/771d79331ca04c159d5c08c57f511038.png
[3bf16eb731c8444d84aa10017e57aab2.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/df6a3f4029374231830301d55a453122.png
[06b1a3c50a3a459389f6213a5cf16cc4.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/e1e76301006949008a44880cceba45a8.png
[MapStruct]: https://mapstruct.org/documentation/stable/reference/html/#implicit-type-conversions
[b735db1c76a34974a79aed37035c42f8.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/6f34b2da038343aaa014a6f5e7e93909.png
[680c0cfc813a4d11afeb723e53c5c67e.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/4f658859967c42e2af3bb0db749be28a.png
[19d3df839b1e48b1b28e073bea8f6ac9.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/5e3a9469b4034fd1a46ec761d1dc574a.png
[2844fafc04234787ae09901d6b444671.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/76e1476cd6e448af9db7542bd9b272fd.png
[8fe0cad0ecd74d048a914674076bc5ec.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/1a2bb6a4114f4e68bc39ad3d81afc045.png
[2cd85c1eec81482ebe1ddcc942d857ea.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/183c2379233d4eb9aef07bd02a7310a0.png
[b98d3ecfecce420ca1d6aee1b746c420.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/caee8119e7b24ae3a48f21dc03c72ccc.png
[7dda17d74030463a936501d1877a5ea7.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/6e81ef8d053241aa8a55eac97135fefa.png
[Java CDI]: https://docs.oracle.com/javaee/6/tutorial/doc/giwhl.html
[f425925984f5451dbeed145433555753.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/29f854650a9d41e996f92e860542f828.png
[dda1a932da69439594eafd983d3beab6.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/162c32bfe06a4bc4aba3f0c44bd94c81.png
[6fefd8e1aa5e4d76bf6fb28f86bb64e9.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/61f21bf493874809881a783c48844185.png
[d4d3a057fe024559a2b22d11cced101a.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/e10039d2eb8547c1acef224898ed6eb3.png
[ceed634e98cb4da9b4f5c4dc4e2f4a96.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/232a99a30f844403b293d32238bedfa9.png
[b0b3947cba2d400cb073e6e3fd577b05.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/f0ef889682054c36a7d266893f990c3f.png
[0461174adb2e4023a0d3bc0b4ead0472.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/3aa06f01a19944378575642aeb557490.png
[544d647ea1cf402cb291973d0e3e2bfa.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/ca6b72e1853c406692c38e97ccd216e4.png
[cea33670a1604a7c8d6904f835deeb7e.png_pic_center]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/21/c4e7dcb109e44a8ba2a18d0a3cc0214e.png
[MapStruct 1]: https://mapstruct.org/documentation/stable/reference/html/