【教程】如何利用MapStruct 解决对象之间转换问题（一）

原创枫秀大淘宝技术

在日常开发中，我们会定义多种不同的Javabean，比如DTO（Data Transfer Object：数据传输对象），DO（Data Object：数据库映射对象，与数据库一一映射），VO（View Object：显示层对象，通常是 Web 向模板渲染引擎层传输的对象）等等这些对象。在这些对象与对象之间转换通常是调对象的set和get方法进行复制，这种转换通常也是很无聊的操作，如果有一个专门的工具来解决Javabean之间的转换问题，让我们从这种无聊的转换操作中解放出来。

MapStruct就是这样一个属性映射工具，用于解决上述对象之间转换问题。MapStruct官网给出的定义：MapStruct是一个Java注释处理器，用于生成类型安全的bean映射类。

本篇文章主要用于记录自己整理的MapStruct使用教程。

简单使用

学习一个新的框架较好的方式是先把demo跑起来，然后一步步的熟悉框架的用法。接下来让我们跑一个简单的demo，简单熟悉MapStruct的使用

通常在项目中，mapStruct和lombox会同时使用，具体的maven配置如下。

    <properties>        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>        <maven.compiler.source>1.8</maven.compiler.source>        <maven.compiler.target>1.8</maven.compiler.target>        <org.mapstruct.version>1.4.2.Final</org.mapstruct.version>        <org.projectlombok.version>1.18.12</org.projectlombok.version>    </properties>
    <dependencies>        <dependency>            <groupId>org.mapstruct</groupId>            <artifactId>mapstruct</artifactId>            <version>${org.mapstruct.version}</version>        </dependency>
        <dependency>            <groupId>org.projectlombok</groupId>            <artifactId>lombok</artifactId>            <version>${org.projectlombok.version}</version>            <scope>provided</scope>        </dependency>
        <dependency>            <groupId>junit</groupId>            <artifactId>junit</artifactId>            <scope>test</scope>            <version>4.12</version>        </dependency>    </dependencies>
<!-- 配置lombok 和mapStruct注解处理器 -->    <build>        <pluginManagement>            <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>                            <path>                                <groupId>org.projectlombok</groupId>                                <artifactId>lombok</artifactId>                                <version>${org.projectlombok.version}</version>                            </path>                        </annotationProcessorPaths>                    </configuration>                </plugin>            </plugins>        </pluginManagement>    </build>

java代码如下：

定义Person实体

@Datapublic class Person {    private String name;    private String lastName;}

定义PersonDTO

@Datapublic class PersonDTO {    private String firstName;    private String lastName;}

使用MapStruct定义Person和PersonDTO之间的转换接口

@Mapperpublic interface PersonMapper {
    PersonMapper INSTANCE = Mappers.getMapper(PersonMapper.class);
    @Mapping(source = "firstName",target = "name")     Person personDTOToPerson(PersonDTO personDTO);}

使用上面定义的转换器，例子如下

public class PersonMapperTest {
    @Test    public void personDTOToPerson() {        PersonMapper personMapper = PersonMapper.INSTANCE;        PersonDTO personDTO = new PersonDTO();        personDTO.setFirstName("feng");        personDTO.setLastName("xiu");        Person person = personMapper.personDTOToPerson(personDTO);        Assert.assertEquals(person.getLastName(),personDTO.getLastName());        Assert.assertEquals(person.getName(),personDTO.getFirstName());    }}

从上面的例子可以看出，使用MapStruct定义一个对象转换器，分为以下几步

创建一个对象转换接口，使用@Mapper注解
定义转换方法，设置需要转换的对象作为参数，返回值是转换后的对象
使用@Mapping注解方法，设置转换对应的属性，如果属性名相同，则不需要设置。
接口中定义一个属性，使用Mappers.getMapper方获取对应的实现，方便使用。

通过上面4步，就可以定义出一个对象转换器，相比于之前来说简单很多。

定义Mapper（Bean映射器）

上面已经看了一个简单的demo，下面我们来具体了解下，如何创建或者说定义一个对象转换器，也就是定义一个Mapper。

▐ 基本的映射

创建一个bean的转换器，只需要定义一个接口，并将需要的转换方法定义在接口中，然后使用org.mapstruct.Mapper注释对其进行注释。
比如上面的PersonMapper

@Mapperpublic interface PersonMapper {
    PersonMapper INSTANCE = Mappers.getMapper(PersonMapper.class);
    @Mapping(source = "firstName",target = "name")     Person personDTOToPerson(PersonDTO personDTO);}

@Mapper注解作用是：在build-time时，MapStruct会自动生成一个实现PersonMapper接口的类。

接口中定义的方法，在自动生成时，默认会将source对象（比如PersonDTO）中所有可读的属性拷贝到target（比如Person）对象中相关的属性，转换规则主要有以下俩条：

当target和source对象中属性名相同，则直接转换
当target和source对象中属性名不同，名字的映射可以通过@Mapping注解来指定。比如上面firstName映射到name属性上。

其实上面PersonMapper通过MapStruct生成的类和我们自己写一个转换类是没有什么区别，上面PersonMapper自动生成的实现类如下：

public class PersonMapperImpl implements PersonMapper {    public PersonMapperImpl() {    }
    public Person personDTOToPerson(PersonDTO personDTO) {        if (personDTO == null) {            return null;        } else {            Person person = new Person();            person.setName(personDTO.getFirstName());            person.setLastName(personDTO.getLastName());            return person;        }    }}

从上面可以看出，MapStruct的哲学是尽可能的生成看起来和手写的代码一样。因此，这也说明MapStruct映射对象属性使用的是getter/setter而不是反射。

正如上面例子这种显示的，在进行映射的时候，也会考虑通过@Mapping中指定的属性。如果指定的属性类型不同，MapStruct可能会通过隐式的类型转换，这个会在后面讲，或者通过调用/创建另外一个映射方法个，这个会在映射对象引用这一节说道。当一个bean的source和target属性是简单类型或者是Bean，才会创建一个新的映射方法，比如属性不能是Collection或者Map类型的属性。至于集合类型的映射将在后面讲。

MapStruct映射target和source的所有公共属性。这包括在父类型上声明的属性。

▐ 在Mapper中自定义转换属性方法

当俩种类型的映射不能通过MapStruct自动生成，我们需要自定义一些方法。自定义方法的方式主要有以下俩种。

如果其他Mapper中已经有此方法，可以在@Mapper(uses=XXXMapper.class)来调用自定义的方法，这样可以方法重用。这个后面会说。

java8或者更新的版本，可以直接在Mapper接口中添加default方法。当参数和返回值类型匹配，则生成的代码会自动调用这个方法。

例子如下

@Mapperpublic interface CarMapper {
    @Mapping(...)    ...    CarDto carToCarDto(Car car);
    default PersonDto personToPersonDto(Person person) {        //hand-written mapping logic    }}

在MapStruct自动生成代码，需要将Person转换成PersonDTO对象时，就会直接调用default方法。

也可以使用抽象类来定义，比如上面的例子使用抽象类定义如下

@Mapperpublic abstract class CarMapper {
    @Mapping(...)    ...    public abstract CarDto carToCarDto(Car car);
    public PersonDto personToPersonDto(Person person) {        //hand-written mapping logic    }}

▐ 多个source参数的映射方法

MapStruct也支持带有多个source参数的映射方法。这个在将多个bean合并成一个bean的时候非常有用。

例子如下：

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

上面显示的就是将俩个source参数映射成一个target对象。和单个参数一样，属性映射也是通过名称。

如果多个source参数中的属性具有相同的名称，必须通过@Mapping指定哪个source里面的属性映射到target属性中。如果存在多个相同的属性，并且没有指定，则会报错。

MapStruct也支持直接引用一个source参数映射到target对象中。例子如下

@Mapperpublic interface AddressMapper {
    @Mapping(source = "person.description", target = "description")    @Mapping(source = "hn", target = "houseNumber")    DeliveryAddressDto personAndAddressToDeliveryAddressDto(Person person, Integer hn);}

上面的例子将hn直接映射到target的houseNumber属性上。

▐ 处理内嵌bean属性映射

例子如下：

 @Mapper public interface CustomerMapper {
     @Mapping( target = "name", source = "record.name" )     @Mapping( target = ".", source = "record" )     @Mapping( target = ".", source = "account" )     Customer customerDtoToCustomer(CustomerDto customerDto); }

如果只是某一个内嵌属性的映射，可以类似@Mapping( target = "name", source = "record.name" )这样写
如果是映射多个内嵌属性到target上，可以用.代替，表示把对应属性bean匹配的内嵌属性映射到target上

▐ 更新Bean实例

有时我们并不一定创建一个新的Bean，可能需要更新某一个实例。这种类型的映射我们可以通过在参数上增加一个@MappingTarget注解。例子如下：

@Mapperpublic interface CarMapper {
    void updateCarFromDto(CarDto carDto, @MappingTarget Car car);}

这个例子会把CarDto中的属性值更新的Car对象实例上。上面的例子我们也可以将void改成Car类型返回值。

对于Collection或者Map类型，默认会将集合中所有的值清空，然后使用相关source集合中的值来填充，即CollectionMappingStrategy.ACCESSOR_ONLY策略。另外也提供了CollectionMappingStrategy.ADDER_PREFERRED 或者 CollectionMappingStrategy.TARGET_IMMUTABLE。这些策略可以在@Mapper(collectionMappingStrategy=CollectionMappingStrategy.TARGET_IMMUTABLE)来指定。

▐ 集合映射

基本的定义方式和普通的bean没什么区别，简单例子如下

@Mapperpublic interface CarMapper {
    Set<String> integerSetToStringSet(Set<Integer> integers);
    List<CarDto> carsToCarDtos(List<Car> cars);
    CarDto carToCarDto(Car car);}

对应的生成方法如下

//GENERATED CODE@Overridepublic Set<String> integerSetToStringSet(Set<Integer> integers) {    if ( integers == null ) {        return null;    }
    Set<String> set = new HashSet<String>();
    for ( Integer integer : integers ) {        set.add( String.valueOf( integer ) );    }
    return set;}
@Overridepublic 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;}

对于Map的映射，还提供了@MapMapping注解,用于处理value的转换
具体的例子如下

public interface SourceTargetMapper {
    @MapMapping(valueDateFormat = "dd.MM.yyyy")    Map<String, String> longDateMapToStringStringMap(Map<Long, Date> source);}

生成的代码如下

//GENERATED CODE@Overridepublic Map<Long, Date> stringStringMapToLongDateMap(Map<String, String> source) {    if ( source == null ) {        return null;    }    Map<Long, Date> map = new HashMap<Long, Date>();    for ( Map.Entry<String, String> entry : source.entrySet() ) {        Long key = Long.parseLong( entry.getKey() );        Date value;        try {            value = new SimpleDateFormat( "dd.MM.yyyy" ).parse( entry.getValue() );        }        catch( ParseException e ) {            throw new RuntimeException( e );        }        map.put( key, value );    }    return map;}

集合映射策略

通过@Mapping#collectionMappingStrategy设置集合的映射策略：CollectionMappingStrategy.ACCESSOR_ONLY：默认、CollectionMappingStrategy.SETTER_PREFERRED、CollectionMappingStrategy.ADDER_PREFERRED、CollectionMappingStrategy.TARGET_IMMUTABLE。

策略具体的意义如果没有看懂，可以参考下这篇文章MapStruct文档（五）——集合映射

▐ 枚举映射处理

枚举映射枚举

直接上例子，方便理解

@Mapperpublic interface OrderMapper {
    OrderMapper INSTANCE = Mappers.getMapper( OrderMapper.class );
    @ValueMappings({        @ValueMapping(source = "EXTRA", target = "SPECIAL"),        @ValueMapping(source = "STANDARD", target = "DEFAULT"),        @ValueMapping(source = "NORMAL", target = "DEFAULT")    })    ExternalOrderType orderTypeToExternalOrderType(OrderType orderType);}

生成的代码如下

// GENERATED CODEpublic 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_;    }}

默认情况下，如果存在不匹配的情形，则直接抛出异常。这种默认行为是可以被修改的，主要有以下三种策略

MappingConstants.NULL : 处理null值，
MappingConstants.ANY_REMAINING : 处理所有未被定义或者名字匹配不上的
MappingConstants.ANY_UNMAPPED ：处理任何违背匹配的情形

枚举与String之间的映射

枚举到字符串的映射，不支持MappingConstants.ANY_REMAINING

@Mapperpublic interface TestMapper {    @ValueMappings({            @ValueMapping(source = "able_status", target = "PERFECT"),            @ValueMapping(source = MappingConstants.NULL, target = "PASS"),            @ValueMapping(source = "failed_status", target = MappingConstants.NULL),            @ValueMapping(source = MappingConstants.ANY_UNMAPPED, target = "normal"),    })    String toEnum(DisableStatus disableStatus);
}
@Componentpublic class TestMapperImpl implements TestMapper {    @Override    public String toEnum(DisableStatus disableStatus) {        if ( disableStatus == null ) {            return "PASS";        }        String string;        switch ( disableStatus ) {            case able_status: string = "PERFECT";            break;            case failed_status: string = null;            break;            default: string = "normal";        }        return string;    }}

字符串到枚举的映射

@Mapperpublic interface TestMapper {
    @ValueMappings({            @ValueMapping(source = "PERFECT", target = "able_status"),            @ValueMapping(source = "PASS", target = MappingConstants.NULL),            @ValueMapping(source = MappingConstants.NULL, target = "failed_status"),            @ValueMapping(source = MappingConstants.ANY_UNMAPPED, target = "normal_status"),    })    DisableStatus toEnum(String disableStatus);
}
@Componentpublic class TestMapperImpl implements TestMapper {
    @Override    public DisableStatus toEnum(String disableStatus) {        if ( disableStatus == null ) {            return DisableStatus.failed_status;        }
        DisableStatus disableStatus1;
        switch ( disableStatus ) {            case "PERFECT": disableStatus1 = DisableStatus.able_status;            break;            case "PASS": disableStatus1 = null;            break;            default: disableStatus1 = DisableStatus.normal_status;        }
        return disableStatus1;    }}
@Mapperpublic interface TestMapper {
    @ValueMappings({            @ValueMapping(source = "PERFECT", target = "able_status"),            @ValueMapping(source = "PASS", target = MappingConstants.NULL),            @ValueMapping(source = MappingConstants.NULL, target = "failed_status"),            @ValueMapping(source = MappingConstants.ANY_REMAINING, target = "normal_status"),    })    DisableStatus toEnum(String disableStatus);
}
@Componentpublic class TestMapperImpl implements TestMapper {
    @Override    public DisableStatus toEnum(String disableStatus) {        if ( disableStatus == null ) {            return DisableStatus.failed_status;        }
        DisableStatus disableStatus1;
        switch ( disableStatus ) {            case "PERFECT": disableStatus1 = DisableStatus.able_status;            break;            case "PASS": disableStatus1 = null;            break;            case "able_status": disableStatus1 = DisableStatus.able_status;            break;            case "disable_status": disableStatus1 = DisableStatus.disable_status;            break;            case "normal_status": disableStatus1 = DisableStatus.normal_status;            break;            case "failed_status": disableStatus1 = DisableStatus.failed_status;            break;            case "ok_status": disableStatus1 = DisableStatus.ok_status;            break;            case "fine_status": disableStatus1 = DisableStatus.fine_status;            break;            default: disableStatus1 = DisableStatus.normal_status;        }
        return disableStatus1;    }}

自定义名称转换

可以通过删除或添加源枚举字符串的前后缀来映射目标枚举对象。

 public enum LevelEnum {    able(1, "完美"),    disable(2, "合格"),    normal(3, "普通"),    failed(4, "不及格"),    ok(5, "还行"),    fine(6, "可以");
    private Integer code;
    private String desc;
    LevelEnum(Integer code, String desc) {        this.code = code;        this.desc = desc;    }
    public Integer getCode() {        return code;    }
    public void setCode(Integer code) {        this.code = code;    }
    public String getDesc() {        return desc;    }
    public void setDesc(String desc) {        this.desc = desc;    }}
public enum DisableStatus {
    able_status(1, "完美"),    disable_status(2, "合格"),    normal_status(3, "普通"),    failed_status(4, "不及格"),    ok_status(5, "还行"),    fine_status(6, "可以");
    private Integer code;
    private String desc;
    DisableStatus(Integer code, String desc) {        this.code = code;        this.desc = desc;    }}
@Mapperpublic interface TestMapper {
    @EnumMapping(nameTransformationStrategy = "stripSuffix", configuration = "_status")    LevelEnum toEnum(DisableStatus disableStatus);
}
@Componentpublic class TestMapperImpl implements TestMapper {
    @Override    public LevelEnum toEnum(DisableStatus disableStatus) {        if ( disableStatus == null ) {            return null;        }
        LevelEnum levelEnum;
        switch ( disableStatus ) {            case able_status: levelEnum = LevelEnum.able;            break;            case disable_status: levelEnum = LevelEnum.disable;            break;            case normal_status: levelEnum = LevelEnum.normal;            break;            case failed_status: levelEnum = LevelEnum.failed;            break;            case ok_status: levelEnum = LevelEnum.ok;            break;            case fine_status: levelEnum = LevelEnum.fine;            break;            default: throw new IllegalArgumentException( "Unexpected enum constant: " + disableStatus );        }
        return levelEnum;    }}

@EnumMapping#nameTransformationStrategy支持的参数有：suffix（添加源后缀）、stripSuffix（删除源后缀）、prefix（添加源前缀）、stripPrefix（删除源前缀）。

检索映射器

前面已经了解如何自定义对象转换器，接下来看看如何使用已经定义好的对象转换器。

▐ 非依赖注入的方式

当我们不使用DI框架，Mapper实例可以通过org.mapstruct.factory.Mappers。只需要调用getMapper方法，传递接口类型的mapper就可以获得MapStruct自动生成的Mapper

像前面的例子，我们可以定义INSTANCE属性用于调用方法。例如

@Mapper(componentModel = "default")public interface CarMapper {
    CarMapper INSTANCE = Mappers.getMapper( CarMapper.class );
    CarDto carToCarDto(Car car);}

通过MapStruct自动生成的mapper是无状态的和线程安全的，可以同时被若干个线程访问。

▐ 使用依赖注入

如果项目使用了依赖注入框架，比如spring。可以使用依赖注入的方式获取映射器。

定义的方式如下：

@Mapper(componentModel = "spring")public interface CarMapper {
    CarDto carToCarDto(Car car);}

使用的方式和普通的spring bean一样，

@AutoWiredprivate CarMapper mapper;

▐ 注入策略

当使用DI注入策略模式时，可以选择field和constructor俩种注入方式。这个可以被@Mapper或者@MapperConfig注解来指定。
使用constructor注入的例子如下：

@Mapper(componentModel = "spring", uses = EngineMapper.class, injectionStrategy = InjectionStrategy.CONSTRUCTOR)public interface CarMapper {    CarDto carToCarDto(Car car);}

生成的映射器将注入uses属性中定义的所有类。当使用InjectionStrategy#CONSTRUCTOR，构造函数将具有适当的注解，而字段则没有。当使用InjectionStrategy#FIELD，注解字段位于field本身。目前，默认的注入策略是field注入。建议使用构造函数注入来简化测试。

▐ 检索总结

检索映射器主要有以下几种，支持的值包括：

default:通过Mapper#getMapper（class）来获取实例
cdi：生成的映射器是一个应用程序范围的CDI bean，可以通过@Inject进行检索
spring：生成的映射器是一个单例范围的spring bean，可以通过@Autowired进行检索
jsr330：生成的映射器用{@code@Named}注释，可以通过@Inject检索，

这些检索策略可以通过@Mapper(componentModel="")来指定，也可以在maven的配置参数里面指定。

总结

通过上面的一些介绍，可以看出我们要做的就是定义一个映射器接口，声明任何必需的映射方法。在编译的过程中，MapStruct会生成此接口的实现。该实现使用纯java方法调用的源对象和目标对象之间的映射。对比手写这些映射方法，MapStruct通过自动生成代码完成繁琐和手写容易出错的代码逻辑从而节省编码时间。遵循配置方法上的约定，MapStruct使用合理的默认值，但在配置或实现特殊行为时不加理会。

同时与动态映射框架相比，MapStruct具有以下优点：