前言

今天我们来介绍一款非常优秀的实体对象映射工具，MapStruct。

在开发的时候我们会看到业务代码之间有很多的JavaBean之间的相互转化，非常影响美观，但是又不得不存在。

通常的JavaBean处理方法是通过Spring或者Apache提供的BeanUtils工具，而对于一些不匹配的属性，通过get/set方法解决。

由于BeanUtils使用反射机制，故其在大量使用时可能会影响到性能，同时对于不匹配的属性，如果较多，get/set起来也非常麻烦和繁琐。

对于一些特殊类型不一致的字段，如DO里为Date类型，可能DTO里需要变为时间的String类型，我们需要调用指定方法进行处理，再进行get/set。

正文

而MapStruct可以让我们从这种复杂而繁琐的工作中解放出来。

MapSturct 是一个生成类型安全，高性能且无依赖的JavaBean映射代码的注解处理器（annotation processor）。

它可以让我们通过注解的方式，生成JavaBean之间的映射代码，相较于反射，更安全更高效。

让我们来看一下。

MapStruct引入

首先我们需要在Maven项目中引入MapSturct的相关Jar包。

<properties>
    <java.version>1.8</java.version>
    <org.mapstruct.version>1.3.1.Final</org.mapstruct.version>
</properties>

<!-- https://mvnrepository.com/artifact/org.mapstruct/mapstruct -->
<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>

有两个，mapstruct是主要包，mapstruct-processor用来辅助生成JavaBean之间的映射代码。

MapStruct使用

我们根据例子来看如何使用MapSturct。

我们这儿有两个JavaBean，PersonDO和PersonDTO，现在我们将PersonDO转为PersonDTO。

@NoArgsConstructor
@AllArgsConstructor
@Data
public class PersonDO {
    private Integer id;
    private String name;
    private int age;
    private String gender;
}

@NoArgsConstructor
@AllArgsConstructor
@Data
public class PersonDTO {
    private String userName;
    private Integer age;
    private Gender gender;
}

1
2
3

public enum Gender {
    MAN,MALE
}

转化时需要编写Mapper，即对象映射器，是一个接口，如下。

@Mapper
public interface PersonConverter {

    PersonConverter INSTANCE = Mappers.getMapper(PersonConverter.class);

    @Mapping(source = "name", target = "userName")
    PersonDTO do2dto(PersonDO person);
}

使用注解@Mapper定义一个Converter接口，在其中定义一个do2dto方法，方法的入参类型是PersonDO，出参类型是PersonDTO，这个方法就用于将PersonDO转成PersonDTO。

测试代码如下：

public class Test {
    public static void main(String[] args) {
        PersonDO personDO = new PersonDO();
        personDO.setName("Sakura");
        personDO.setAge(27);
        personDO.setId(1);
        personDO.setGender(Gender.MAN.name());

        PersonDTO personDTO = PersonConverter.INSTANCE.do2dto(personDO);
        System.out.println(personDTO);
    }
}

输出结果

1	PersonDTO(userName=Sakura, age=27, gender=MAN)

由上面的例子可以看到MapSturct成功将PersonDO转成PersonDTO。

MapStruct字段映射处理

两个JavaBean对象进行映射，属性名称一致的字段可以相互映射，不一致的如何处理呢？

两个字段名字不一致

从上面的例子可以看出，我们只需要使用@Mapping注解。在转换方法上设置

1	@Mapping(source = "name", target = "userName")

即可。其含义是将name字段的值映射给userName。

MapStruct可以映射的类型

在上面例子，我们发现age字段完成映射，其类型一个为int，另一个为包装类。

gender字段完成映射，其类型一个为枚举，一个为String。

一般情况下，MapSturct会对部分类型做自动映射，而不需要我们额外配置。

基本类型及其他们对应的包装类型。
基本类型的包装类型和String类型之间
String类型和枚举类型之间

自定义常量和默认值

如果我们想在转换中，给某个属性一个固定值，可以使用constant。

比如PersonDTO里新增身高字段。而PersonDO里没有，那么我们可以在转换时赋予默认值。

@NoArgsConstructor
@AllArgsConstructor
@Data
public class PersonDTO {
    private String userName;
    private Integer age;
    private Gender gender;
    private Integer height;
}

1	@Mapping(target = "height",constant = "175")

而对于某一个属性，如果映射后为空，我们可以给予其默认值，使用defaultValue，如下：

1	@Mapping(target = "gender",defaultValue = "MAN")

类型不一致的映射

在实际转化中，有可能字段类型是不一致的，如何进行映射呢？

我们使用上面的例子，在PersonDO里增加生日属性，为Date类型，PersonDTO里为String类型。

@NoArgsConstructor
@AllArgsConstructor
@Data
public class PersonDO {
    private Integer id;
    private String name;
    private int age;
    private String gender;
    private Date birthday;
}

@NoArgsConstructor
@AllArgsConstructor
@Data
public class PersonDTO {
    private String userName;
    private Integer age;
    private Gender gender;
    private Integer height;
    private String birthday;
}

这时候我们可以使用如下方法转化。

@Mapping(source = "name", target = "userName")
@Mapping(target = "height",constant = "175")
@Mapping(target = "birthday",dateFormat = "yyyy-MM-dd HH:mm:ss")
PersonDTO do2dto(PersonDO person);

运行后可以看到正确输出结果：

1	PersonDTO(userName=Sakura, age=27, gender=MAN, height=175, birthday=2020-08-17 15:20:16)

dateFormat是MapStruct自带的属性，如果我们的属性映射方法比较复杂呢？

当然，MapStruct支持我们自定义属性转换的方法，我们来看一下。

我们新增一个兴趣爱好字段，如下：

@NoArgsConstructor
@AllArgsConstructor
@Data
public class PersonDO {
    private Integer id;
    private String name;
    private int age;
    private String gender;
    private Date birthday;
    private List<Integer> hobbies;
}
@NoArgsConstructor
@AllArgsConstructor
@Data
public class PersonDTO {
    private String userName;
    private Integer age;
    private Gender gender;
    private Integer height;
    private String birthday;
    private List<String> strHobbies;
}
public enum HobbiesEnum {
    FOOTBALL(1,"足球"),
    READ_BOOK(2,"读书"),
    PLAY_GAME(3,"玩游戏"),
    SINGING(4,"唱歌"),
    TRAVEL(5,"旅行");
    private Integer value;
    private String desc;

    //get/set 构造器略

    /**
     * 获取一个枚举
     * @param value
     * @return
     */
    public static HobbiesEnum getEnum(Integer value){
        return Arrays.stream(HobbiesEnum.values()).filter(e->e.value.equals(value)).findFirst().orElse(null);
    }
}

需要完成List hobbies对List strHobbies的转化，我们可以使用如下代码：

@Mapper
public interface PersonConverter {
    PersonConverter INSTANCE = Mappers.getMapper(PersonConverter.class);

    @Mapping(source = "name", target = "userName")
    @Mapping(target = "height",constant = "175")
    @Mapping(target = "gender",defaultValue = "MAN")
    @Mapping(target = "birthday",dateFormat = "yyyy-MM-dd HH:mm:ss")
    @Mapping(target = "strHobbies",expression = "java(getHobbiesStr(person.getHobbies()))")
    PersonDTO do2dto(PersonDO person);
    /**
     * 爱好映射
     * @param integers
     * @return
     */
    default List<String> getHobbiesStr(List<Integer> integers){
        List<String> list = new ArrayList<>();
        for (Integer integer : integers) {
            HobbiesEnum hobbiesEnum = HobbiesEnum.getEnum(integer);
            if(hobbiesEnum!=null){
                list.add(hobbiesEnum.getDesc());
            }
        }
        return list;
    }
}

PS：java1.8接口支持自定义default方法，expression = “java(getHobbiesStr(person.getHobbies()))”这段代码也可以指向自己写的某个方法，需要具体路径包名。

上面代码还是非常好理解的，这儿就不过多叙述。

多个属性映射

MapStruct还支持将多个实体数据组装到一个实体中，如下：

比如上面的例子，我们的身高属性来自另一个Bean，则代码如下：

@NoArgsConstructor
@AllArgsConstructor
@Data
public class HeightDO {
    private String id;
    private Integer height;
}

则组装数据的方法如下：

@Mapping(source = "person.name", target = "userName")
@Mapping(source = "height.height",target = "height")
@Mapping(target = "gender",defaultValue = "MAN")
@Mapping(target = "birthday",dateFormat = "yyyy-MM-dd HH:mm:ss")
@Mapping(target = "strHobbies",expression = "java(getHobbiesStr(person.getHobbies()))")
PersonDTO do2dto(PersonDO person,HeightDO height);

对于source属性，需要指定来自哪个DO。

public class Test {
    public static void main(String[] args) {
        PersonDO personDO = new PersonDO();
        personDO.setName("Sakura");
        personDO.setAge(27);
        personDO.setId(1);
        personDO.setBirthday(new Date());
        personDO.setGender(Gender.MAN.name());
        List<Integer> list  =new ArrayList<>();
        list.add(1);
        list.add(3);
        personDO.setHobbies(list);

        HeightDO heightDO = new HeightDO();
        heightDO.setHeight(178);

        PersonDTO personDTO = PersonConverter.INSTANCE.do2dto(personDO,heightDO);
        System.out.println(personDTO);
    }
}

输出结果：

1	PersonDTO(userName=Sakura, age=27, gender=MAN, height=178, birthday=2020-08-17 15:52:14, strHobbies=[足球, 玩游戏])

更新现有Bean实例

MapStruct还支持将一个Bean的属性更新到另一个Bean的同名属性里。

1	void updateDTOfromDO(PersonDO person, @MappingTarget PersonDTO personDTO);

需要注意这个对于同名属性，如果DO上有值，那么DTO上的值将被覆盖，如下：

PersonDTO dto = new PersonDTO();
dto.setAge(15);

PersonDO aDo = new PersonDO();
aDo.setName("Sakura");
aDo.setAge(27);
aDo.setId(1);
aDo.setBirthday(new Date());
aDo.setGender(Gender.MAN.name());

PersonConverter.INSTANCE.updateDTOfromDO(aDo,dto);
System.out.println(dto);

输出结果：

1	PersonDTO(userName=null, age=27, gender=MAN, height=null, birthday=2020/8/17 下午4:29, strHobbies=null)

继承反转配置

MapStruct在存在DO转换为DTO的前提下，还支持将DTO转换为DO，而且不用我们复杂的配置。

方法如下：

@Mapper
public interface PersonConverter {

    PersonConverter INSTANCE = Mappers.getMapper(PersonConverter.class);

    @Mapping(source = "name", target = "userName")
    @Mapping(target = "height",constant = "175")
    @Mapping(target = "gender",defaultValue = "MAN")
    @Mapping(target = "birthday",dateFormat = "yyyy-MM-dd HH:mm:ss")
    @Mapping(target = "strHobbies",expression = "java(getHobbiesStr(person.getHobbies()))")
    PersonDTO do2dto(PersonDO person);


    @InheritInverseConfiguration(name = "do2dto")
    PersonDO dto2do(PersonDTO personDTO);
}

我们只需要@InheritInverseConfiguration注解即可解决，name属性指向DO转换为DTO的方法。

测试：

PersonDTO dto1 = new PersonDTO();
dto1.setAge(27);
dto1.setBirthday("2018-11-11 12:12:12");
dto1.setGender(Gender.MAN);
dto1.setHeight(175);
dto1.setUserName("Sakura");
List<String> list1 = new ArrayList<>();
list1.add("足球");
list1.add("玩游戏");
dto1.setStrHobbies(list1);
PersonDO personDO1 = PersonConverter.INSTANCE.dto2do(dto1);
System.out.println(personDO1);

输出：

1	PersonDO(id=null, name=Sakura, age=27, gender=MAN, birthday=Sun Nov 11 12:12:12 CST 2018, hobbies=null)

这儿需要注意的是我们看到Hobbies属性并没有转化，这是正常的，这个需要我们配置@Mapping，写出并指定兴趣爱好转化的逆向方法。

MapStruct的性能

MapStruct的性能是非常优秀的，我们来测试一下：

为简化代码，我们是DO和DTO尽可能的简单。

@AllArgsConstructor
@NoArgsConstructor
@Data
public class TestDO {
    private Integer a;
}

@NoArgsConstructor
@AllArgsConstructor
@Data
public class TestDTO {
    private Integer a;
}

MapStruct相关方法：

@Mapper
public interface TestConverter {
    TestConverter INSTANCE = Mappers.getMapper(TestConverter.class);

    TestDTO do2dto(TestDO testDO);
}

我们使用Spring自带的BeanUtils工具类来与其进行比较：

public class Test {
    final static int NUM = 100000;
    public static void main(String[] args) {
        long start1 = System.currentTimeMillis();
        for (int i =0;i<NUM;i++){
            TestDO testDO = new TestDO();
            testDO.setA(i);
            TestDTO testDTO = new TestDTO();
            BeanUtils.copyProperties(testDO,testDTO);
        }
        System.out.println("BeanUtils属性拷贝耗时："+(System.currentTimeMillis()-start1)+"ms");

        long start2 = System.currentTimeMillis();
        for (int i =0;i<NUM;i++){
            TestDO testDO = new TestDO();
            testDO.setA(i);
            TestDTO dto = TestConverter.INSTANCE.do2dto(testDO);
        }
        System.out.println("MapStruct处理耗时："+(System.currentTimeMillis()-start2)+"ms");
    }
}

我们以100000个对象为样本，得到如下输出结果：

1 2	BeanUtils属性拷贝耗时：1903ms MapStruct处理耗时：5ms

可以看到差距是非常大的。

MapStruct为什么有如此优秀的性能呢？

其实核心点在于：MapStruct在编译期间，就生成了对象映射代码，确保了高性能，同时编译期间也可以发现可能存在的映射问题。

在上面的TestConverter中，经过代码编译后，MapStruct会生成一个TestConverterImpl的实现类，帮我们进行对象属性转换。

如下：

@Generated(
    value = "org.mapstruct.ap.MappingProcessor",
    date = "2020-08-17T17:00:26+0800",
    comments = "version: 1.3.1.Final, compiler: javac, environment: Java 9 (Oracle Corporation)"
)
public class TestConverterImpl implements TestConverter {

    @Override
    public TestDTO do2dto(TestDO testDO) {
        if ( testDO == null ) {
            return null;
        }

        TestDTO testDTO = new TestDTO();

        testDTO.setA( testDO.getA() );

        return testDTO;
    }
}

这样在运行之前就相当于我们手写get/set方法，相比反射，速度更快。

其编译工作主要由mapstruct-processor包完成。

PS：PersonConverterImpl的相关实现这儿就不展示了，大家可以看下它是如何处理的，比如对于一些自定义方法等。

总结

本文介绍了一款Java对象映射工具，MapStruct。相比传统BeanUtils有着更高的性能。

映射代码在编译期间生成，相当于替我们手写了get/set，不仅相比反射具有很好的性能，同时还可以在编译期间发现可能存在的映射问题。

越努力越幸运

Java实体对象映射工具MapStruct

前言

正文