MapStruct POJO 映射框架指南

# 前言

本文将会主要讲解后端开发中 VO、DTO、Entity 相互转化方式，并且针对其中比较成熟的框架 MapStruct 进行解读和教学

# 问题

微服务架构下，服务拆分会产生 VO、DTO、Entity 三类 POJO

VO 用于前端接口参数传递，例如用于 http 接口接收请求参数。可以继承扩展 DTO，或者直接使用 DTO
DTO 用于 rpc 接口参数传递。单独定义，或者继承扩展其他 rpc 接口的 DTO
Entity（PO）用于 orm 映射处理，与表结构对应，只在服务内部使用，不能对外

注：对于 POJO 的解释可以查看文章后面的补充章节

微服务架构面向不同场景的 POJO 定义，引入前端请求处理问题，也就是三者之间的转换：

请求：VO => DTO => Entity
返回：Entity => DTO => VO

# 结构

Entity

@Data
@TableName(value = "orders", schema = "crazy1984")
public class Order {
    @TableId(type = IdType.AUTO)
    private int id;
    private String orderId;
    private String orderType;
    private int orderStatus;
    private Date createdAt;
    private Date updatedAt;
}

1
2
3
4
5
6
7
8
9
10
11

DTO

@Data
public class OrderDTO {
    private String orderId;
    private String orderType;
    private int orderStatus;
    private Date createdAt;
}

1
2
3
4
5
6
7

@Data
public class OrderVO extends OrderDTO{
    private String orderTypeName;
    private String orderStatusName;
}

1
2
3
4
5

# 手动转换

我们可以使用最直接的方法，通过代码对 POJO 属性进行逐个拷贝

但是这样的方式太低效，给开发人员增加许多低效的重复劳动，也不易维护（比如新增字段时，所有相关处都要同步修改）

OrderDTO dto = new OrderDTO();
dto.setOrderId(entity.getOrderId());
dto.setOrderType(entity.getOrderType());
dto.setOrderStatus(entity.getOrderStatus());
dto.setCreatedAt(entity.getCreatedAt());

1
2
3
4
5

# 工具类转换

改进方法为，使用工具类进行同名属性的自动拷贝，例如使用 Spring 的 BeanUtils

OrderDTO dto = new OrderDTO();
BeanUtils.copyProperties(entity, dto);

1
2

这样可以减少大量工作，但是会带来如下不足：

不支持属性名映射，属性名必须完全相同
不支持自动类型转换，Spring 的 BeanUtils 要求源属性与目标属性的类型是相互 assignable 的
性能损耗大，属性拷贝中的属性名匹配、类型检查、写权限检查都是动态判断，有性能损耗

除此之外，还有很多工具类，下图为各类工具类对比：

拷贝工具	使用效率
Spring BeanUtils	使用方便，效率中等
Cglib BeanCopier	使用方便，效率最高
Apache BeanUtils	使用方便，效率低，原因为该工具做了很多校验，兼容，日志打印等，导致性能下降（阿里约束规范中禁止使用该工具）
Apache PropertyUtils	使用方便，效率低
Hutool BeanUtil	使用方便，封装完善，效率较高

# 映射框架转换

目前有很多开源成熟的 mapping 框架：

以上框架均支持不同属性名的映射，自动类型转换，递归映射自定义对象属性

实现原理为基于反射机制，实现类属性的 get，set 调用，基于注解、配置，来实现不同属性名的映射和类型转化

框架的性能对比，MapStruct 和 JMapper 性能较好。因为他们的映射过程是静态化的，所以实际性能和自己手写 get、set 一样

并且在开发过程中，可以通过检查生成的代码来确保映射转换没有错误，相比 ModelMapper 的黑盒实现更加可靠。对于 grpc 协议 protobuf 对象和 entity 的互相转换，也能很好的支持

下面我们将会详细讲解 MapStruct 框架的使用

# MapStruct

# 简介

官方仓库：mapstruct/mapstruct: An annotation processor for generating type-safe bean mappers (github.com) (opens new window)

官方文档：MapStruct – Java bean mappings, the easy way! (opens new window)

MapStruct 是代码生成器，基于约定而不是配置，极大地简化 Java Bean 类型之间映射的实现

# 安装

官方文档：Installation – MapStruct (opens new window)

首先我们需要向 pom.xml 中添加如下内容

注：本文使用 Maven 为例，Gradle 用户可以参照上方的官方文档

...
<properties>
    <org.mapstruct.version>1.5.5.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.8.1</version>
            <configuration>
                <source>1.8</source> <!-- depending on your project -->
                <target>1.8</target> <!-- depending on your project -->
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${org.mapstruct.version}</version>
                    </path>
                    <!-- other annotation processors -->
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

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

# 示例

官方示例代码：mapstruct-examples/mapstruct-mapper-repo at main · mapstruct/mapstruct-examples (github.com) (opens new window)

我们可以直接单独下载上面对应 demo 的项目文件夹，具体方法参照文末补充章节

您也可以自行创建 Spring 项目，然后依次安装 MapStruct 后，创建如下文件

Car.java

@Data
@AllArgsConstructor
@NoArgsConstructor
public class Car {

    private String make;
    private int numberOfSeats;
    private CarType type;
    
}

1
2
3
4
5
6
7
8
9
10

CarType.java

public enum CarType {
    SPORTS, OTHER;
}

1
2
3

CarDto.java

@Data
@AllArgsConstructor
@NoArgsConstructor
public class CarDto {

    private String make;
    private int seatCount;
    private String type;

}

1
2
3
4
5
6
7
8
9
10

CarMapper.java

@Mapper
public interface CarMapper {
 
    CarMapper INSTANCE = Mappers.getMapper( CarMapper.class );
 
    @Mapping(source = "numberOfSeats", target = "seatCount")
    CarDto carToCarDto(Car car);
}

1
2
3
4
5
6
7
8

TestMapperRepo.java

public class TestMapperRepo {
    @Test
    public void shouldMapCarToDto() {
        //given
        Car car = new Car("Morris", 5, CarType.SPORTS);

        //when
        CarDto carDto = CarMapper.INSTANCE.carToCarDto(car);

        //then
        assertThat(carDto).isNotNull();
        assertThat(carDto.getMake()).isEqualTo("Morris");
        assertThat(carDto.getSeatCount()).isEqualTo(5);
        assertThat(carDto.getType()).isEqualTo("SPORTS");
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

但是 MapStruct 默认是和 Lombok 冲突的，无法识别，会出现属性找不到错误，您可以将 Lombok 注释替换为对应代码，或者是 pom.xml 替换如下

<properties>
    <org.projectlombok.version>1.18.16</org.projectlombok.version>
    <org.mapstruct.version>1.5.5.Final</org.mapstruct.version>
    <lombok-mapstruct-binding.version>0.2.0</lombok-mapstruct-binding.version>
</properties>

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

    <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.8.1</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${org.projectlombok.version}</version>
                    </path>
                    <!-- This is needed when using Lombok 1.18.16 and above -->
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok-mapstruct-binding</artifactId>
                        <version>${lombok-mapstruct-binding.version}</version>
                    </path>
                    <!-- Mapstruct should follow the lombok path(s) -->
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${org.mapstruct.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>