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

DTO

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

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

手动转换

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

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

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

工具类转换

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

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

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

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

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

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

映射框架转换

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

Dozer - Usage (sourceforge.net)
Orika reference guide (orika-mapper.github.io)
ModelMapper - Simple, Intelligent, Object Mapping.
MapStruct – Java bean mappings, the easy way!
JMapper Framework (jmapper-framework.github.io)

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

实现原理为基于反射机制，实现类属性的 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)

官方文档：MapStruct – Java bean mappings, the easy way!

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

安装

官方文档：Installation – MapStruct

首先我们需要向 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>

示例

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

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

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

Car.java

@Data
@AllArgsConstructor
@NoArgsConstructor
public class Car {

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

CarType.java

public enum CarType {
    SPORTS, OTHER;
}

CarDto.java

@Data
@AllArgsConstructor
@NoArgsConstructor
public class CarDto {

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

}

CarMapper.java

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

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

但是 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>