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

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

1.简单使用

通常在项目中，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>

官方maven配置:

############mapper Struct###########
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.mapstruct.examples.lombok</groupId>
    <artifactId>mapstruct-examples-lombok</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>
    <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.1.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>
        <!-- lombok dependencies should not end up on classpath -->
        <!-- 如果 MapStruct 生成的实现类里面，只创建了对象没有对属性进行 set 可能是版本没匹配，使用官方给的这个版本就好了 -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${org.projectlombok.version}</version>
            <scope>provided</scope>
        </dependency>
        <!-- IntelliJ pre 2018.1.1 requires the mapstruct processor to be present as provided dependency -->
        <!-- 高版本的 IDEA 就不需要添加这个依赖了 -->
        <!--
            <dependency>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>${org.mapstruct.version}</version>
                <scope>provided</scope>
            </dependency>
        -->
    </dependencies>
    <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>
</project>

java代码如下：
定义Person实体

@Data
public class Person {
    private String name;
    private String lastName;
}

定义PersonDTO

@Data
public class PersonDTO {
    private String firstName;
    private String lastName;
}

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

@Mapper
public 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步，就可以定义出一个对象转换器，相比于之前来说简单很多。

2定义Mapper（Bean映射器）

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

2.1 基本的映射

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


@Mapper
public 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的所有公共属性。这包括在父类型上声明的属性。

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

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

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

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

例子如下

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

在MapStruct自动生成代码，需要将Person转换成PersonDTO对象时，就会直接调用default方法。
也可以使用抽象类来定义，比如上面的例子使用抽象类定义如下

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

2.3 多个source参数的映射方法

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

例子如下：

@Mapper
public 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对象中。例子如下


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

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

2.4处理内嵌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上

2.5 更新Bean实例
有时我们并不一定创建一个新的Bean，可能需要更新某一个实例。这种类型的映射我们可以通过在参数上增加一个@MappingTarget注解。例子如下：
```
@Mapper
public 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)来指定。

2.6 集合映射

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

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

对应的生成方法如下

//GENERATED CODE
@Override
public 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;
}
@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;
}

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

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

生成的代码如下

//GENERATED CODE
@Override
public 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;
}

2.7 集合映射策略

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

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

2.8 枚举映射处理

2.8.1枚举映射枚举

直接上例子，方便理解

@Mapper
public 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 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_;
    }
}

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

MappingConstants.NULL : 处理null值，
MappingConstants.ANY_REMAINING : 处理所有未被定义或者名字匹配不上的

MappingConstants.ANY_UNMAPPED ：处理任何违背匹配的情形

2.8.2枚举与String之间的映射

枚举到字符串的映射，不支持MappingConstants.ANY_REMAINING ```java @Mapper public 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);

}

@Component public 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; } }

字符串到枚举的映射
```java
@Mapper
public 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);
}
@Component
public 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;
    }
}
@Mapper
public 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);
}
@Component
public 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;
    }
}

2.8.3自定义名称转换

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

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;
    }
}
@Mapper
public interface TestMapper {
    @EnumMapping(nameTransformationStrategy = "stripSuffix", configuration = "_status")
    LevelEnum toEnum(DisableStatus disableStatus);
}
@Component
public 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（删除源前缀）。

3.检索映射器

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

3.1非依赖注入的方式

当我们不使用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);
}

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

@AutoWired
private CarMapper mapper;

3.2注入策略

当使用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注入。建议使用构造函数注入来简化测试。

3.3检索总结

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

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

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

博客专栏

如何利用MapStruct 解决对象之间转换问题