MapStruct - Java bean 映射，简单的方法！

蔬菜界的香菜

已于 2022-09-02 17:23:47 修改

阅读量431

点赞数 1

分类专栏： Java 文章标签： java 开发语言

于 2022-09-02 17:23:19 首次发布

本文链接：https://blog.csdn.net/weixin_40222901/article/details/126667462

版权

Java 专栏收录该内容

4 篇文章 0 订阅

订阅专栏

应用程序通常需要在不同的对象模型（例如实体和 DTO）之间进行映射，
如：在前后台传输过程中，持久层定义的实体类经常需要映射到其它的对象模型进行相互转换。

MapStruct

MapStruct 是一个代码生成器，在不同的对象模型（例如实体和 DTO）之间进行映射，它基于约定优于配置的方法，极大地简化了 Java bean 类型之间的映射实现。

MapStruct 是一个 Java注释处理器，用于生成类型安全、高性能和无依赖关系的 bean 映射代码。

与其他映射框架相比，MapStruct 在编译时生成 bean 映射，这确保了高性能，允许开发人员快速的反馈和彻底的错误检查。

引用

Maven - pom.xml

<properties>
    <org.mapstruct.version>1.5.2.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>
                <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.gradle

plugins {
    ...
    id "com.diffplug.eclipse.apt" version "3.26.0" // Only for Eclipse
}

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（例如一个JPA 实体）和一个数据传输对象 CarDto（DTO）。示例一：

public class Car {
    private String manufacturer;
    private int numberOfSeats;
    private int price;

public class CarDto {
    private String make;
    private int seatCount;
    private String price;

定义映射器的接口，只需在定义的接口上使用注解：org.mapstruct.Mapper，示例二：

@Mapper
public interface CarMapper {

    @Mapping(target = "manufacturer", source = "make")
    @Mapping(target = "seatCount", source = "numberOfSeats")
    CarDto carToCarDto(Car car);

    @Mapping(target = "fullName", source = "name")
    PersonDto personToPersonDto(Person person);
}

在生成的方法实现中，源类型（例如 Car）中的所有可读属性都将被复制到目标类型（例如 CarDto）中的相应属性中：

当一个属性与其对应的目标实体同名时，它将被隐式映射。
当一个属性在目标实体中具有不同的名称时，可以通过 @Mapping 注解指定其名称

@Mapper 使 MapStruct 代码生成器 CarMapper 在构建时创建接口的实现（在 target 目录下对应的路径下）。示例三：

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

    @Override
    public PersonDto personToPersonDto(Person person) {
        //...
    }
}

编译后的代码，看起来像自己写的代码，特别是，这意味着通过普通的 getter/setter 调用而不是反射或类似方法将值从源复制到目标。

MapStruct 在许多情况下会自动处理类型转换。生成的代码考虑了通过指定的任何名称映射 @Mapping。

1、源对象和目标对象不同的类型，也就是隐式类型转换：

目前自动应用以下转换：

在所有 Java 原始数据类型和它们对应的包装器类型之间，例如：int，Integer and boolean 等 Boolean。
生成的代码是有 null 意识的，即当将包装器类型转换为相应的原始类型时，null 将执行检查。
在所有 Java 原始数字类型和包装类型之间，例如：int、long 或 byte、Integer。
在所有 Java 原始类型（包括它们的包装器）和 String 之间，例如：在 int 和 String 或 Boolean 和 String。
java.text.DecimalFormat 可以指定被理解的格式字符串。
在 Enum类型和 String 之间。
在大数字类型（java.math.BigInteger, java.math.BigDecimal）和 Java 原始类型（包括它们的包装器）以及字符串之间。
java.text.DecimalFormat可以指定被理解的格式字符串。
在 java.util.Date/XMLGregorianCalendar 和 String 之间。java.text.SimpleDateFormat 可以通过选项指定格式字符串。
…

示例四：从 int 到 String 的转换

@Mapper
public interface CarMapper {

    @Mapping(source = "price", numberFormat = "$#.00")
    CarDto carToCarDto(Car car);

    @IterableMapping(numberFormat = "$#.00")
    List<String> prices(List<Integer> prices);
}

示例五：从 BigDecimal 到 String 的转换

@Mapper
public interface CarMapper {

    @Mapping(source = "power", numberFormat = "#.##E0")
    CarDto carToCarDto(Car car);

}

示例六：从 Date 到 String 的转换

@Mapper
public interface CarMapper {

    @Mapping(source = "manufacturingDate", dateFormat = "dd.MM.yyyy")
    CarDto carToCarDto(Car car);

    @IterableMapping(dateFormat = "dd.MM.yyyy")
    List<String> stringListToDateList(List<Date> dates);
}

2、源对象包含其他对象与目标对象的转换，也就是映射对象引用：

通常，一个对象不仅具有原始属性，而且还引用其他对象。
例如，Car 类可以包含对 Person 应该映射到该类引用的对象的对象（代表汽车的驾驶员）的 PersonDto 引用 CarDto。

在这种情况下，只需为引用的对象类型定义一个映射方法，示例七：

@Mapper
public interface CarMapper {

    CarDto carToCarDto(Car car);

    PersonDto personToPersonDto(Person person);
}

carToCarDto() 方法的生成代码将调用 personToPersonDto() 用于映射 driver属性的方法，
而生成的实现用于 personToPersonDto() 执行人员对象的映射。

在生成映射方法的实现时，MapStruct 将为源对象和目标对象中的每个属性对应用以下例程：

如果源和目标属性具有相同的类型，则该值将直接从源复制到目标。如果该属性是一个集合（例如 a List），则该集合的副本将被设置到目标属性中。
如果源属性类型和目标属性类型不同，请检查是否存在其他映射方法，其参数类型为源属性类型，返回类型为目标属性类型。如果存在这样的方法，它将在生成的映射实现中调用。
如果不存在这样的方法，MapStruct 将查看属性的源和目标类型的内置转换是否存在。如果是这种情况，生成的映射代码将应用此转换。
如果不存在这样的方法，MapStruct 将应用复杂的转换：
a.映射方法，映射方法映射的结果，像这样：target = method1( method2( source ) )

b.内置转换，通过映射方法映射的结果，如下所示：target = method( conversion( source ) )

c.映射方法，内置转换映射的结果，如下所示：target = conversion( method( source ) )

如果没有找到这样的方法，MapStruct 将尝试生成一个自动子映射方法，该方法将在源属性和目标属性之间进行映射。
如果 MapStruct 无法创建基于名称的映射方法，则会在构建时引发错误，指示不可映射的属性及其路径。

映射控件 ( MappingControl) 可以在所有级别 ( @MapperConfig, @Mapper, @BeanMapping, @Mapping) 上定义。

3、源对象和目标对象同为集合类型进行转换，也就是映射集合：

集合类型（List Set 等）的映射与映射 bean 类型的方式相同，即通过在映射器接口中定义具有所需源和目标类型的映射方法。
MapStruct 支持 Java 集合框架中的各种可迭代类型。示例八：

@Mapper
public interface CarMapper {

    Set<String> integerSetToStringSet(Set<Integer> integers);

    List<CarDto> carsToCarDtos(List<Car> cars);

    CarDto carToCarDto(Car car);
}

生成的实现为每个元素执行从到 integerSetStringSet 的转换，而生成的方法为每个包含的元素调用方法，
如示例九所示：

//GENERATED CODE
@Override
public Set<String> integerSetToStringSet(Set<Integer> integers) {
    if ( integers == null ) {
        return null;
    }

    Set<String> set = new LinkedHashSet<String>();

    for ( Integer integer : integers ) {
        set.add( String.valueOf( integer ) );
    }

    return set;
}

@Override
public List<CarDto> carsToCarDtos(List<Car> cars) {
    if ( cars == null ) {
        return null;
    }

    List<CarDto> list = new ArrayList<CarDto>();

    for ( Car car : cars ) {
        list.add( carToCarDto( car ) );
    }

    return list;
}

4、源枚举中的每个常量都映射到目标枚举类型中同名的常量。映射值：

@ValueMapping 如果需要，可以在注释的帮助下将源枚举中的常量映射到具有另一个名称的常量。
源枚举中的几个常量可以映射到目标类型中的同一个常量。示例十：

@Mapper
public interface OrderMapper {

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

    @ValueMappings({
        @ValueMapping(target = "SPECIAL", source = "EXTRA"),
        @ValueMapping(target = "DEFAULT", source = "STANDARD"),
        @ValueMapping(target = "DEFAULT", source = "NORMAL")
    })
    ExternalOrderType orderTypeToExternalOrderType(OrderType orderType);
}

生成的代码。示例十一：

/ GENERATED CODE
public class OrderMapperImpl implements OrderMapper {

    @Override
    public ExternalOrderType orderTypeToExternalOrderType(OrderType orderType) {
        if ( orderType == null ) {
            return null;
        }

        ExternalOrderType externalOrderType_;

        switch ( orderType ) {
            case EXTRA: externalOrderType_ = ExternalOrderType.SPECIAL;
            break;
            case STANDARD: externalOrderType_ = ExternalOrderType.DEFAULT;
            break;
            case NORMAL: externalOrderType_ = ExternalOrderType.DEFAULT;
            break;
            case RETAIL: externalOrderType_ = ExternalOrderType.RETAIL;
            break;
            case B2B: externalOrderType_ = ExternalOrderType.B2B;
            break;
            default: throw new IllegalArgumentException( "Unexpected enum constant: " + orderType );
        }

        return externalOrderType_;
    }
}

5、多个源参数的映射：
例如：将几个实体组合成一个数据传输对象。示例十二：

@Mapper
public interface AddressMapper {

    @Mapping(target = "description", source = "person.description")
    @Mapping(target = "houseNumber", source = "address.houseNo")
    DeliveryAddressDto personAndAddressToDeliveryAddressDto(Person person, Address address);
}

所示的映射方法采用两个源参数并返回一个组合的目标对象。与单参数映射方法一样，属性按名称映射。

@Mapping 如果多个源对象定义具有相同名称的属性，则必须使用注释指定从中检索属性的源参数，如示例中的 description属性所示。
对于在给定源对象中只存在一次的属性，可以选择指定源参数的名称，因为它可以自动确定。

6、条件映射：String 属性不为 null 且不为空时映射。
增加注解 org.mapstruct.Condition 的 @Condition 返回的方法 boolean 类型。

@Mapper
public interface CarMapper {

    CarDto carToCarDto(Car car);

    @Condition
    default boolean isNotEmpty(String value) {
        return value != null && !value.isEmpty();
    }
}