使用MapStruct框架实现Bean之间属性映射

在实际项目开发过程中我们经常会遇到把A类的属性复制到B类中的这种场景,比如实体类DO对象从数据库查询出来,在给到调用方之前很可能需要转成DTO传输对象,那这个时候就需要将DO对象的字段值复制到DTO对象中,如果字段比较少可能你手写就行了,但如果要复制的字段比较多,超过50个,并且这种场景在项目中出现频繁,该怎么办?仍然还是去手写,然后一点一点复杂吗?如果这样做那效率必然是低下的,而且没有一点儿技术含金量,花大把时间写这种样本代码对自己成长帮助不大。接下来介绍的是一款让你更优雅的实现Bean之间属性映射的框架,并且在同类框架中性能是最好的。

介绍

MapStruct是一个代码生成器,它基于约定优于配置的方法极大地简化了Java bean类型之间映射的实现。

通过上面的介绍我们应该能够理解到这么几点,首先它是一个代码生成器,就是用来帮开发者自动生成代码的工具,只需要通过简单的代码就可以实现原来手工编写的样板代码,因为它采用约定大于配置的设计思想,所以开发者只需要掌握简单的代码编写就可以了。

也就是说人家框架帮你自动生成了原先手工编写的代码,但实际上那些手工编写的代码还是存在的,只不过你没有编写,框架帮你自动生成了而已。这其实也回到框架的本质,事情还是那些事,就看你来做,还是它来做,它如果多做,你就少做,甚至可以不做。这里提到的指的是各种框架,它的本质就是帮开发者做了一些事情。

特点

与动态映射框架相比,MapStruct具有以下优点:

  • 通过使用普通方法调用而不是反射来快速执行
  • 速度快:由于MapStruct不采用所谓的反射机制,而是像开发者原来手工逐个赋值那样编码,所以没有额外的性能损失,跟你自己写的代码是一样的。
  • 编译时类型安全性
  • 展示生成报告:在生成代码过程中如果发现映射不完整、不正确会立即输出日志。

集成

介绍如何在项目中集成进来。

工作原理

在做这件事情之前我们要搞清楚它的运行原理,它到底是怎么生成代码的?

  1. 在代码编译时会触发MapStruct插件运行
  2. 当MapStruct运起来之后会扫描它自己特定注解的类
  3. 解析类中的方法按照自己的策略在项目编译目录(build)下生成实现类,如果生成过程中出现异常则会输出日志,并中断当前整个项目编译工作。

在项目中集成MapStruct框架

在项目中添加MapStruct的依赖,并且配置MapStruct编译插件,让程序在编译时触发MapStruct插件工作,否则代码肯定不会生成,那在客户端调用时就会出错。

  • 如果是maven项目,在pom文件中添加下面的代码:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
<properties>
<org.mapstruct.version>1.3.1.Final</org.mapstruct.version>
</properties>

<dependencies>
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct</artifactId>
<version>${org.mapstruct.version}</version>
</dependency>
</dependencies>

<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.5.1</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
<annotationProcessorPaths>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>${org.mapstruct.version}</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
</build>
  • 如果是gradle项目,在build文件中添加下面的代码:
1
2
3
4
5
6
7
dependencies {
implementation "org.mapstruct:mapstruct:${mapstructVersion}"
annotationProcessor "org.mapstruct:mapstruct-processor:${mapstructVersion}"

// If you are using mapstruct in test code
testAnnotationProcessor "org.mapstruct:mapstruct-processor:${mapstructVersion}"
}

使用示例

如果我们需要将Car对象的属性赋值给CarDto对象,那可以按照下面方法做:

  • 定义一个接口,如下所示就可以了。
1
2
3
4
5
6
@Mapper
public interface CarMapper {
@Mapping(source = "make", target = "manufacturer")
@Mapping(source = "numberOfSeats", target = "seatCount")
CarDto carToCarDto(Car car);
}

基于上面的约定MapStruct将自动生成下面的代码,看起来是不是跟自己以前手工编写的差不多?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
// GENERATED CODE
public class CarMapperImpl implements CarMapper {

@Override
public CarDto carToCarDto(Car car) {
if ( car == null ) {
return null;
}

CarDto carDto = new CarDto();

if ( car.getFeatures() != null ) {
carDto.setFeatures( new ArrayList<String>( car.getFeatures() ) );
}
carDto.setManufacturer( car.getMake() );
carDto.setSeatCount( car.getNumberOfSeats() );
carDto.setDriver( personToPersonDto( car.getDriver() ) );
carDto.setPrice( String.valueOf( car.getPrice() ) );
if ( car.getCategory() != null ) {
carDto.setCategory( car.getCategory().toString() );
}
carDto.setEngine( engineToEngineDto( car.getEngine() ) );

return carDto;
}

private EngineDto engineToEngineDto(Engine engine) {
if ( engine == null ) {
return null;
}

EngineDto engineDto = new EngineDto();

engineDto.setHorsePower(engine.getHorsePower());
engineDto.setFuel(engine.getFuel());

return engineDto;
}
}

看到这里你应该明白了,通过简单的接口定义就可以不用写那么多样板代码,真是太爽了。MapStruct给开发者的选择很灵活,你不用非得用接口来向它告诉你的约定,你可以用抽象类,或者就是普通的类,这些都可以,具体可以看看官方文档。

主要功能介绍

由于官方文档实在时写的太详细了,本文实在没有理由赘述一遍, 所以在此把MapStruct能够实现的功能特性列举出来,让大家在遇到类似问题时知道它可以有方案解决。

说明:源(source)对象指的是从哪个Bean中复制数据,目标(target)对象指的是要把源对象的数据复制到哪个Bean对象中去。可以理解Bean之间映射就是一个从哪到哪的过程。

  1. 支持maven/gradle/ant工具所构建的项目
  2. 在某些情况下,可能需要手动实现从一种类型到另一种类型的特定映射,而MapStruct无法生成这种映射,你可以向映射器中添加自定义方法。
  3. 可以用多个源对象的数据映射到一个对象上,也就是说可以同时把A和B的数据复制到C对象中。
  4. 可以通过引用更新目标对象,默认在复制时会生成新的对象并返回,但有时候可能不需要生成新的对象,只希望它在既有对象上进行复制。
  5. Bean的字段如果没有提供getter/setter方法也可以进行复制,它会通过实例直接访问属性来达到目的。
  6. 如果Bean提供了自己的工厂,即通过Builder构造自己,也可以被识别到。
  7. 获取映射器之后客户端才能调用,获取的方式支持Mappers工厂、CDI依赖注入和Spring依赖注入。
  8. 类型隐式转换
  9. 嵌套对象自动映射
  10. 在当前映射器中可以调用其他映射器,可以是自定义映射器。
  11. 集合映射
  12. 流映射
  13. 枚举类映射
  14. 映射字段控制:常量,默认值,忽略字段,NULL值检查和处理策略,异常处理
  15. 映射配置共享、继承和反向映射
  16. 装饰器映射,也就是在映射前后做一些自定义操作。
  17. 提供SPI接口,可以修改框架的部分实现。

参考文献:

  1. https://mapstruct.org/documentation/stable/reference/html