MapStruct 使用指南

Posted 戴泽supp

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了MapStruct 使用指南相关的知识，希望对你有一定的参考价值。

MapStruct 使用指南

文章目录

一、背景

在我们开发的软件系统中，有着各式各样用于存储数据的实体，按照一般标准，可分为以下几类

  • POJO（Plain Ordinary Java Object）：简单 Java 对象，就是普通 Java 对象，普通 JavaBeans ,有时可以作为 VO（value-object）或 DTO（Data Transfer Object）来使用
  • VO（View Object）：视图对象，用于与前端的交互的展示层，作用是封装返回给前端的数据起
  • DTO（Data Transfer Object）：数据传输对象，泛指用于各个层级间的数据传输对象。即提取依赖资源中所需要的的属性，同时减少不需要的属性，来提高传输速度，以及减少流量。
  • Entity ：entity里的每一个字段，与数据库相对应。
  • 。。。

上述几类实体，经常需要互相转换，而手动创建 bean 映射器非常耗时，有没有更简单的解决方案呢？

MapStruct 应运而生，它可以自动生成 Bean 映射器类，来完成各个实体键数据的传输

在本文中，我们将深入研究 MapStruct。

二、简介

MapStruct 是一个开源的基于 Java 的代码生成器，用于创建实现 Java Bean 之间转换的扩展映射器。

使用 MapStruct，我们只需要创建接口，而该库会通过注解，在编译过程中自动创建具体的映射实现，大大减少了通常需要手工编写的样板代码的数量。

三、MapStruct 依赖

  • 注意：mapstruct 与 lombok 版本必须匹配，否则会出现映射不上的问题。

1、Maven

    <dependencies>
        <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct</artifactId>
            <version>1.2.0.Final</version>
        </dependency>

        <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct-processor</artifactId>
            <version>1.2.0.Final</version>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.4</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                    <encoding>UTF-8</encoding>
                </configuration>
            </plugin>
        </plugins>
    </build>

由于 MapStruct 在编译时工作，并且会集成到像 Maven 和 Gradle 这样的构建工具上，我们还必须在 <build/> 标签中添加一个插件 maven-compiler-plugin。

并在其配置中添加 annotationProcessorPaths，该插件会在构建时生成对应的代码（这一步也可以不加，直接在依赖中添加 mapstruct-processor ,如上）

<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>
                    
                    // 同时使用了 lombok ，必须加上这个，否则编译不通过
                    <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                            <version>$lombok.version</version>
                        </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

2、Gradle

plugins 
    id 'net.ltgt.apt' version '0.20'


apply plugin: 'net.ltgt.apt-idea'
apply plugin: 'net.ltgt.apt-eclipse'

dependencies 
    compile "org.mapstruct:mapstruct:$mapstructVersion"
    annotationProcessor "org.mapstruct:mapstruct-processor:$mapstructVersion"

net.ltgt.apt 插件会负责处理注释。你可以根据使用的 IDE 启用插件 apt-idea 或 apt-eclipse 插件。

MapStruct 及其 处理器 的最新稳定版本都可以从 Maven中央仓库 中获得。

四、映射

1、基本映射

实例讲解

public class Doctor 
    private int id;
    private String name;
    // getters and setters or builder


public class DoctorDto 
    private int id;
    private String name;
    // getters and setters or builder

为了在这两者之间进行映射，我们要创建一个 DoctorMapper 接口。对该接口使用 @Mapper 注解，MapStruct 就会知道这是两个类之间的映射器。

@Mapper
public interface DoctorMapper 
    DoctorMapper INSTANCE = Mappers.getMapper(DoctorMapper.class);
    DoctorDto toDto(Doctor doctor);

当我们构建/编译应用程序时，MapStruct 注解处理器插件会识别出 DoctorMapper 接口并为其生成一个实现类。

public class DoctorMapperImpl implements DoctorMapper 
    @Override
    public DoctorDto toDto(Doctor doctor) 
        if ( doctor == null ) 
            return null;
        
        DoctorDtoBuilder doctorDto = DoctorDto.builder();

        doctorDto.id(doctor.getId());
        doctorDto.name(doctor.getName());

        return doctorDto.build();

使用

DoctorDto doctorDto = DoctorMapper.INSTANCE.toDto(doctor);

注意：你可能也注意到了上面实现代码中的DoctorDtoBuilder。因为 builder 代码往往比较长，为了简洁起见，这里省略了builder模式的实现代码。如果你的类中包含Builder，MapStruct 会尝试使用它来创建实例；如果没有的话，MapStruct 将通过 new 关键字进行实例化。

2、不同字段间映射

public class Doctor 
    private int id;
    private String name;
    private String specialty;
    // getters and setters or builder


public class DoctorDto 
    private int id;
    private String name;
    private String specialization;
    // getters and setters or builder


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

    @Mapping(source = "doctor.specialty", target = "specialization")
    DoctorDto toDto(Doctor doctor);

这个注解代码的含义是：Doctor 中的 specialty 字段对应于 DoctorDto 类的 specialization 。

编译之后，自动生成以下实现类

public class DoctorMapperImpl implements DoctorMapper 
@Override
    public DoctorDto toDto(Doctor doctor) 
        if (doctor == null) 
            return null;
        

        DoctorDtoBuilder doctorDto = DoctorDto.builder();

        doctorDto.specialization(doctor.getSpecialty());
        doctorDto.id(doctor.getId());
        doctorDto.name(doctor.getName());

        return doctorDto.build();

3、多个源类

有时候，需要将多个类中的值聚合为一个 DTO，以下为演示代码：

public class Education 
    private String degreeName;
    private String institute;
    private Integer yearOfPassing;
    // getters and setters or builder


public class DoctorDto 
    private int id;
    private String name;
    private String degree;
    private String specialization;
    // getters and setters or builder


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

    @Mapping(source = "doctor.specialty", target = "specialization")
    @Mapping(source = "education.degreeName", target = "degree")
    DoctorDto toDto(Doctor doctor, Education education);

如果 Education 类和 Doctor 类包含同名的字段，我们必须让映射器知道使用哪一个，否则它会抛出一个异常。

举例来说，如果两个模型都包含一个 id 字段，我们就要选择将哪个类中的 id 映射到 DTO 属性中。

4、子对象映射

多数情况下，POJO 中不会只包含基本数据类型，其中往往会包含其它类，MapStruct 也支持对类里面的复杂对象，进行映射，演示代码如下：

public class Patient 
    private int id;
    private String name;
    // getters and setters or builder


public class Doctor 
    private int id;
    private String name;
    private String specialty;
    private List<Patient> patientList;
    // getters and setters or builder


public class PatientDto 
    private int id;
    private String name;
    // getters and setters or builder


public class DoctorDto 
    private int id;
    private String name;
    private String degree;
    private String specialization;
    private List<PatientDto> patientDtoList;
    // getters and setters or builder


@Mapper
public interface PatientMapper 
    PatientMapper INSTANCE = Mappers.getMapper(PatientMapper.class);
    PatientDto toDto(Patient patient);


@Mapper(uses = PatientMapper.class)
public interface DoctorMapper 

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

    @Mapping(source = "doctor.patientList", target = "patientDtoList")
    @Mapping(source = "doctor.specialty", target = "specialization")
    DoctorDto toDto(Doctor doctor);

因为我们要处理另一个需要映射的类，所以这里设置了 @Mapper 注解的 uses 标志，这样现在的 @Mapper 就可以使用另一个 @Mapper 映射器。我们这里只加了一个，但你想在这里添加多少 class/mapper 都可以。

我们已经添加了 uses 标志，所以在为 DoctorMapper 接口生成映射器实现时，MapStruct 也会把 Patient 模型转换成 PatientDto ——因为我们已经为这个任务注册了 PatientMapper。

实现代码：

public class DoctorMapperImpl implements DoctorMapper 
    private final PatientMapper patientMapper = Mappers.getMapper( PatientMapper.class );

    @Override
    public DoctorDto toDto(Doctor doctor) 
        if ( doctor == null ) 
            return null;
        

        DoctorDtoBuilder doctorDto = DoctorDto.builder();

        doctorDto.patientDtoList( patientListToPatientDtoList(doctor.getPatientList()));
        doctorDto.specialization( doctor.getSpecialty() );
        doctorDto.id( doctor.getId() );
        doctorDto.name( doctor.getName() );

        return doctorDto.build();
    
    
    protected List<PatientDto> patientListToPatientDtoList(List<Patient> list) 
        if ( list == null ) 
            return null;
        

        List<PatientDto> list1 = new ArrayList<PatientDto>( list.size() );
        for ( Patient patient : list ) 
            list1.add( patientMapper.toDto( patient ) );
        

        return list1;

5、更新现有实例

有时，需要用 DTO 的最新值更新一个模型中的属性，对目标对象使用 @MappingTarget 注解，就可以更新现有的实例.

@Mapper(uses = PatientMapper.class)
public interface DoctorMapper 

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

    @Mapping(source = "doctorDto.patientDtoList", target = "patientList")
    @Mapping(source = "doctorDto.specialization", target = "specialty")
    void updateModel(DoctorDto doctorDto, @MappingTarget Doctor doctor);

重新生成实现代码，就可以得到 updateModel() 方法：

public class DoctorMapperImpl implements DoctorMapper 

    @Override
    public void updateModel(DoctorDto doctorDto, Doctor doctor) 
        if (doctorDto == null) 
            return;
        

        if (doctor.getPatientList() != null) 
            List<Patient> list = patientDtoListToPatientList(doctorDto.getPatientDtoList());
            if (list != null) 
                doctor.getPatientList().clear();
                doctor.getPatientList().addAll(list);
             else 
                doctor.setPatientList(null);
            
         else 
            List<Patient> list = patientDtoListToPatientList(doctorDto.getPatientDtoList());
            if (list != null) 
                doctor.setPatientList(list);
            
        
        doctor.setSpecialty(doctorDto.getSpecialization());
        doctor.setId(doctorDto.getId());
        doctor.setName(doctorDto.getName());

五、数据类型转换

1、数据类型映射

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 官方文档。
public class PatientDto 
    private int id;
    private String name;
    private LocalDate dateOfBirth;
    // getters and setters or builder


public class Patient 
    private int id;
    private String name;
    private String dateOfBirth;
    // getters and setters or builder


@Mapper
public interface PatientMapper 

    @Mapping(source MapStruct类型之间映射的实现


 MapStruct类型之间映射的实现


 MapStruct类型之间映射的实现


 MapStruct 一文读懂


 MapStruct 使用指南


 MapStruct 使用指南