前言

日常开发中，不同JavaBean之间的拷贝是非常常见的，常用的框架有：Spring BeanUtils、Apache BeanUtils、Dozer、Orika、JMapper、MapStruct等。

BeanUtils等是基于反射调用get，set方法，性能相对较弱，并且你不知道它是如何处理每个字段的映射的。

而手写get、set方法又太麻烦，维护也不是很方便，比如新增字段、删除字段等，都需要去手动调整。

MapStruct就比较折中，它会在编译阶段自动帮你生成get、set方法，兼具了手写get、set的性能和BeanUtils的便捷，并且还可以看到自动生成的代码，同时还有强大的字段自定义映射的功能。

本文将介绍MapStruct的常见使用方法。

准备工作

先引入依赖，以Maven为例：

...
<properties>
    <org.mapstruct.version>1.4.2.Final</org.mapstruct.version>
</properties>
...
<dependencies>
    <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>
</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>
                    <!--如果使用了lombok最好加上，否则编译器不会生成get、set方法-->
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${lombok.version}</version>
                    </path>
                    <!--如果 Lombok 版本为 1.18.16 及以上，需要添加，否则可以不用-->
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok-mapstruct-binding</artifactId>
                        <version>0.1.0</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

如果使用的是IDEA，可以额外装个插件：MapStruct Support，可以有自动提示，当然，这也不是必须的。

快速上手

举个栗子

假设有如下两个对象需要做转换

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

@Data
public class UserVO {
    private String userName;
    private Integer age;
    private Date birthday;
    private String gender;
}

只需创建一个UserConverter的接口或抽象类

@Mapper
public interface UserConverter {
    //获取生成的实现类
    UserConverter INSTANCE = Mappers.getMapper(UserConverter.class);

    UserVO convert(UserDO person);
}

使用

UserDO userDO = new UserDO(1, "张三", 25, new Date(), "男");
UserVO userVO = UserConverter.INSTANCE.convert(userDO);

以上便是MapStruct最基本的使用了，相比于BeanUtils麻烦的地方在于，需要定义一个接口，然后写一个转换的方法。

项目编译以后就会生成如下的实现类，文件位于项目中的target/generated-sources/annotations/...

@Generated(
    value = "org.mapstruct.ap.MappingProcessor",
    date = "2022-05-07T19:03:37+0800",
    comments = "version: 1.4.2.Final, compiler: javac, environment: Java 1.8.0_291 (Oracle Corporation)"
)
public class UserConverterImpl implements UserConverter {

    @Override
    public UserVO convert(UserDO person) {
        if ( person == null ) {
            return null;
        }

        UserVO userVO = new UserVO();

        userVO.setAge( person.getAge() );
        userVO.setBirthday( person.getBirthday() );
        userVO.setGender( person.getGender() );

        return userVO;
    }
}

通过这个生成的实现类，我们可以很清晰得知道MapStruct是如何映射每个字段的。

如果你两个转换的对象字段名和类型都完全一致的话，那只需要这样就可以了，MapStruct会根据字段名自动去做映射，即隐式映射，不需要额外的配置。

更新存在的实例

上面的方式是new一个新的实例出来，有时候我们可能已经有一个实例对象了，希望给这个已有的实例set值，则可以这么写

void convert(UserDO source, @MappingTarget UserVO target);

此时convert方法返回空，UserVO前面增加了一个@MappingTarget注解，这个注解是告诉MapStruct我们需要将值写入到这个对象中。

生成的代码如下：

...
@Override
public void convert(UserDO source, UserVO target) {
    if ( source == null ) {
        return;
    }

    target.setAge( source.getAge() );
    target.setGender( source.getGender() );
    target.setBirthday( source.getBirthday() );
}
...

定义映射器

基础使用

有些时候两个对象可能会有字段不完全一样的情况（类型不一致或者字段名不一致），则此时需要使用@Mapping手动指定映射关系，下面以最常见的两种情况为例，介绍下@Mapping的基本使用方法。

字段名不同、类型相同

上面定义的两个对象中，有两个名称不一致的字段：

//UserDO
private String name;

//UserVO
private String userName;

由于字段名不同，所以MapStruct就做不了映射了，需要在convert方法上加上@Mapping注解：

@Mapping(source = "name", target = "userName")
UserVO convert(UserDO person);

source就是UserBO中的字段名，target就是UserVO中的字段名，做好映射以后MapStruct就会为我们生成对应的代码：

...
userVO.setUserName( person.getName() );
...

字段名相同、类型不同

我们做转换的对象可能会出现字段名一致，但是类型不同的情况，以上面两个对象为例，改变下birthday的类型：

//UserDO
private Date birthday;

//UserVO
private Long birthday;

UserVO中改成了Long型，如果此时编译，则会报错，因为MapStruct不知道如何将Date转换成Long，这个时候就需要写一个转换方法了，所以UserConverter会变成这样：

@Mapper
public interface UserConverter {
    //获取生成的实现类
    UserConverter INSTANCE = Mappers.getMapper(UserConverter.class);

    //指定映射关系，此处可不写
    @Mapping(target = "birthday", expression = "java(date2Long(person.getBirthday()))")
    UserVO convert(UserDO person);

    //在UserConverter中增加一个默认方法
    default Long date2Long(Date date) {
        return date != null ? date.getTime() : null;
    }
}

稍微有点点麻烦了，特别是@Mapping中的expression，写起来很麻烦的样子，但实际上，如果你的转换类还不是很复杂，就如现在这样的话，这个@Mapping是可以省去的，MapStruct会根据入参和返回值类型，自动匹配你定义的方法，即隐式调用，所以你即使不写@Mapping，MapStruct也会使用你的date2Long方法去转换birthDay的值（看上去很智能，但有时候也会弄巧成拙，后文会提到）。

但是如果你的Mapper接口比较复杂了，里面定义了出参和返回值相同的两个方法，则必须使用@Mapping指定使用哪个方法（或者使用@Named标记方法防止隐式调用，后文会提到），否则在编译时MapStruct会因为不知道用哪个方法而报错。

当然你可以不用想这么多，先编译再说，如果报错了再去处理即可，这也是MapStruct的一个好处：在编译期就可以发现对象转换的错误，而不是到运行时。

再说说这个expression，其实就是允许你写一段java代码，格式：java(<EXPRESSION>)，括号里写代码即可。如果你安装了我刚刚说的IDEA的插件，还能有智能提示。

最终会生成如下代码：

...
userVO.setBirthday( date2Long(person.getBirthday()) );
...

@Mapping注解

上面简单介绍了下最常见的用法，@Mapping还提供了很多其他的参数，常用的如下：

target：上文已介绍过，目标对象的字段名，同一目标属性不得多次映射。
source：上文已介绍过，数据源对象的字段名。此属性不能与constant()或expression()一起使用。
expression：上文已介绍过，表达式必须以 Java 表达式的形式给出，格式如下： java( )。

表达式中引用的任何类型都必须通过它们的完全限定名称给出。或者，可以通过Mapper.imports()导入类型。

🌟此属性不能与source() 、 defaultValue() 、 defaultExpression() 、 qualifiedBy() 、 qualifiedByName()或constant()一起使用。
ignore：如果设置为true，则指定的字段不会做转换，默认false。
dateFormat：如果属性从String映射到Date或反之亦然，则可以由SimpleDateFormat处理的格式字符串。

对于所有其他属性类型和映射枚举常量时，将被忽略。例：dateFormat = "yyyy-MM-dd HH:mm:ss"
numberFormat：如果带注释的方法从Number映射到String ，则可以由DecimalFormat处理的格式字符串，反之亦然。

对于所有其他元素类型将被忽略。例：numberFormat = "$#.00"
defaultValue：默认值。如果 source 属性为null ，则会使用此处的默认值。如果target字段不是String类型，会尝试找到可以匹配的转换方法，否则会报错。

🌟此属性不能与constant() 、 expression()或defaultExpression()一起使用。
constant：不管原属性值，直接将目标属性设置为指定的常量。如果target字段不是String类型，会尝试找到可以匹配的转换方法，否则会报错。

🌟此属性不能与source() 、 defaultValue() 、 defaultExpression()或expression()一起使用。
qualifiedBy：使用自定义方法对target字段赋值
qualifiedByName：

其他参数就不一一说明了，掌握这些已经可以应付绝大多数情况，实在不行，就写个转换方法，然后用expression就行了。

@Mapping注解复用

如果我们对一个业务对象定义了多个JavaBean，比如UserDO，UserVO，UserRequest等，里面都需要将userName映射成name，或者gender映射成sex等，那在多个convert方法上都去写重复的@Mapping就很麻烦了，后面调整修改也要修改多处。所以可以通过自定义新的注解的方式来复用@Mapping。

@Mapping注解除了可以加在方法上，还可以加在注解上，我们可以自定义一个注解，如：

@Mapping(target = "sex", source = "gender")
@Mapping(target = "name", source = "userName")
public @interface UserMapping {
}

此时，在convert方法上加@UserMapping就等于加那两个Mapping注解

//原写法
@Mapping(target = "sex", source = "gender")
@Mapping(target = "name", source = "userName")
UserVO convert(UserDO person);

/**********************分割线**********************/

//自定义新注解以后的写法
@UserMapping
UserVO convert(UserDO person);

关闭隐式映射

上文提到了MapStruct会进行隐式映射，如果你不希望这样，可以在方法上加上@BeanMapping(ignoreByDefault = true)来关闭隐式映射，此时，只有定义了@Mapping的字段才会做转换

关闭隐式调用

隐式调用提供了很大的方便，但有时候这种智能的行为也会带来一些麻烦。

假设有这么一个场景，对某个特定的字段值需要转大写，比如身份证号（末位可能是X），如果在Mapper接口中定义一个转大写的默认方法，则所有target和source为String类型的字段都会去调用这个方法来转换：

//接口定义
@Mapper
public interface UserConverter {
    UserVO convert(UserDO person);

    default String upperCase(String s) {
        return s != null ? s.toUpperCase() : null;
    }
}

//生成的实现类
public class UserConverterImpl implements UserConverter {

    @Override
    public UserVO convert(UserDO person) {
        if ( person == null ) {
            return null;
        }

        UserVO userVO = new UserVO();

        userVO.setUserName( upperCase( person.getName() ) );
        userVO.setBirthday( date2Long( person.getBirthday() ) );
        userVO.setAge( person.getAge() );
        userVO.setIdCard( upperCase( person.getIdCard() ) );
        userVO.setGender( upperCase( person.getGender() ) );

        return userVO;
    }
}

可以看到，除了idCard字段外，name、gender字段也都使用了upperCase方法，这不是我们想要的。

有两种方法解决这个问题：

自定义注解

这是官方提供的一种方法，原文可以参考：https://mapstruct.org/faq/#How-to-avoid-MapStruct-selecting-a-method

方法就是自己定义一个注解，名称可以随意，只要用@org.mapstruct.Qualifier标记即可

@Qualifier // 需要使用org.mapstruct.Qualifier
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.CLASS)  // RetentionPolicy必须为CLASS
public @interface DoIgnore {
}

然后把这个注解加在定义的默认方法上，MapStruct就不会主动去调用了，需要你声明才行

@Mapper
public interface UserConverter {
    @Mapping(target = "idCard", expression = "java(upperCase(person.getIdCard()))")
    UserVO convert(UserDO person);

    @DoIgnore
    default String upperCase(String s) {
        return s != null ? s.toUpperCase() : null;
    }
}

使用@org.mapstruct.Named注解

自定义一个额外的注解比较麻烦，所以可以使用MapStruct提供的注解，看下这个注解的定义，发现它上面也标记了@Qualifier，所以标记了这个注解的方法也不会被隐式调用

@Target( { ElementType.TYPE, ElementType.METHOD } )
@Retention( RetentionPolicy.CLASS )
@Qualifier
public @interface Named {

    /**
     * A name qualifying the annotated element
     *
     * @return the name.
     */
    String value();
}

这个注解的功能就是给方法指定一个别名，然后和@Mapping#qualifiedByName结合使用，上面的例子就会变成这样

@Mapper
public interface UserConverter {
    @Mapping(target = "idCard", qualifiedByName = "upper")
    UserVO convert(UserDO person);

    @Named("upper")
    default String upperCase(String s) {
        return s != null ? s.toUpperCase() : null;
    }
}

使用@Named后，调用方法可以用qualifiedByName取代之前的expression，又稍微简洁了一些~

是否关闭隐式映射和隐式调用是依据具体场景来的，看情况结合使用即可。好在最不济MapStruct也可以查看生成的方法，以此来规避一些预期之外的错误。

嵌套属性的映射

一些复杂的对象里面可能某个属性也是一个对象，如：

@Data
@AllArgsConstructor
@NoArgsConstructor
public static class UserDO {
    private Integer id;
    private String name;
    private Integer age;
    private Date birthday;
    private String gender;

    private UserInfo userInfo;
}

@Data
public static class UserInfo {
    private String idCard;
    private String avatar;
}

@Data
public static class UserVO {
    private String userName;
    private Integer age;
    private String idCard;
    private Long birthday;
    private String gender;
    private String avatar;
}

可以使用.引用内部的字段，有两种写法，两者是等价的：

//第一种写法：逐一指定各个资源的映射关系
//优点：方便精细控制需要转换的字段
@Mapping(source = "userInfo.idCard", target = "idCard")
@Mapping(source = "userInfo.avatar", target = "avatar")
UserVO convert(UserDO person);

//第二种写法：利用隐式转换对所有同名字段做转换
//优点：书写简单
@Mapping(source = "userInfo", target = ".")
UserVO convert(UserDO person);

生成的方法

public class MapStructDemo$UserConverterImpl implements UserConverter {

    @Override
    public UserVO convert(UserDO person) {
        if ( person == null ) {
            return null;
        }

        UserVO userVO = new UserVO();

        userVO.setUserName( person.getName() );
        userVO.setBirthday( date2Long( person.getBirthday() ) );
        userVO.setIdCard( personUserInfoIdCard( person ) );
        userVO.setAvatar( personUserInfoAvatar( person ) );
        userVO.setAge( person.getAge() );
        userVO.setGender( person.getGender() );

        return userVO;
    }

    //自动生成的方法
    private String personUserInfoIdCard(UserDO userDO) {
        if ( userDO == null ) {
            return null;
        }
        UserInfo userInfo = userDO.getUserInfo();
        if ( userInfo == null ) {
            return null;
        }
        String idCard = userInfo.getIdCard();
        if ( idCard == null ) {
            return null;
        }
        return idCard;
    }

    //自动生成的方法
    private String personUserInfoAvatar(UserDO userDO) {
        if ( userDO == null ) {
            return null;
        }
        UserInfo userInfo = userDO.getUserInfo();
        if ( userInfo == null ) {
            return null;
        }
        String avatar = userInfo.getAvatar();
        if ( avatar == null ) {
            return null;
        }
        return avatar;
    }
}

多参数映射

多个入参也支持转换，并且同样会使用隐式映射对名字字段做转换，对于不同名字的则需要手动指定

//额外的字段映射，格式为：{参数名}.{字段名}，如
//  @Mapping(source = "person.xx", target = "xx")
//  @Mapping(source = "userInfo.xxxx", target = "xxxx")
@Mapping(target = "birthday", qualifiedByName = "date2Long")
UserVO convert(UserDO person, UserInfo userInfo);

//单个字段也可以直接映射
@Mapping(source = "num", target = "age")
UserVO convert(UserDO person, Integer num);

🌟 一些注意事项：

具有多个源参数的映射方法将在所有源参数为空的情况下才返回 null。否则，目标实体将被实例化，同时将所有来自所提供参数的属性值映射到目标实体中，如果与预期不符，则只能自行实现方法。

//UserVO convert(UserDO person, UserInfo userInfo)生成的方法如下
@Override
public UserVO convert(UserDO person, UserInfo userInfo) {
    if ( person == null && userInfo == null ) {
        return null;
    }

    UserVO userVO = new UserVO();

    if ( person != null ) {
        userVO.setBirthday( date2Long( person.getBirthday() ) );
        userVO.setAge( person.getAge() );
        userVO.setGender( person.getGender() );
    }
    if ( userInfo != null ) {
        userVO.setIdCard( userInfo.getIdCard() );
        userVO.setAvatar( userInfo.getAvatar() );
    }

    return userVO;
}

如果多个源参数中指定了同名的字段，必须使用@Mapping指定，否则会报错

@Mapper注解

@Mapper为自定义的Mapper接口提供了一系列的配置项，常用的如下：

componentModel：指定生成的映射器应遵循的组件模型，总共支持4种模式
- default: 这是默认的情况，MapStruct不使用任何组件类型，可以通过Mappers.getMapper(Class)方式获取自动生成的实例对象。
- spring: 生成的实现类上面会自动添加一个@Component注解，可以通过Spring的 @Autowired方式进行注入。下面会详细说明。
- cdi: 生成的映射器是应用程序范围的 CDI bean，可以通过@Inject检索。
- jsr330: 生成的实现类上会添加@javax.inject.Named 和@Singleton注解，可以通过 @Inject注解获取。
uses：引用其他Mapper接口，可以指定多个。
unmappedSourcePolicy和unmappedTargetPolicy：对未映射的字段的处理策略，默认为警告，可以改为忽略或者报错。
imports：为实现类引入外部方法，如果@Mapping的expression中使用了外部的方法，可以用这个引入，避免在java()中写完整路径。
config：可以引用标记了@MapperConfig的Class作为配置的模板。@Mapper中设置的配置将优先于@MapperConfig中的设置。可以指定多个。后面会介绍这个参数的使用。

其他的一些并不常用（主要是没用过...），此处不一一介绍了。

与Spring结合

大部分项目都会使用spring框架，MapStruct也对spring提供了支持。

比如上面定义的UserConverter中需要使用Mappers.getMapper来获取实现类，这个方式略显麻烦，因为每个Mapper接口都要写上这么一句，所以可以改成如下：

@Mapper(componentModel = "spring")
public interface UserConverter {
    ......
}

指定componentModel = spring以后，生成的实现类会变成这样：

@Component
public class UserConverterImpl implements UserConverter {
    ......
}

其他都没有变，只是多了一个@Component注解，有了这个注解以后，我们就知道可以使用自动装配了：

//默认方式
UserConverter.INSTANCE.convert();

/**********************分割线**********************/

//spring的方式
@Autowired
private UserConverter userConverter;
...
userConverter.convert();
...

配置继承

假如你希望给每个Mapper接口都配置一堆参数的话，还是挺麻烦的，所以，MapStruct提供了@MapperConfig，可以由其他Mapper引用配置，达到复用的目的：

//定义一个配置项
@MapperConfig(componentModel = "spring", 
    unmappedSourcePolicy = ReportingPolicy.IGNORE, 
    unmappedTargetPolicy = ReportingPolicy.IGNORE)
public interface MapStructConfig {
}

//Mapper引用
@Mapper(config = MapStructConfig.class)
public interface UserConverter {
}

这样就不用重复写配置了，@MapperConfig和@Mapper拥有同样的字段属性，如果@Mapper使用了配置项并且没有额外定义的话，就将使用@MapperConfig中的配置，如果定义同样的字段，则以@Mapper中的为准。

上面提到的uses属性可以使用其他Mapper中的转换方法，达到复用的目的。

不过需要注意的是，如果@Mapper中componentModel设置为了spring，则uses的Mapper也需要使用这种方法，否则会报错。

拓展用法

以上为基础用法，泛用性最好，自由度最高，比较推荐。

除此之外，再介绍两种方式，但是有一定的局限性。

MapStruct Spring Extensions

这是官方推出的一个Spring插件，支持通过继承org.springframework.core.convert.converter.Converter来实现统一对象转换方法的调用。这篇文章讲得比较详细了，此处不再赘述：https://mp.weixin.qq.com/s/XrmchQUiKcQ9ooteq-6ZlQ

但是这种方式依然还是需要定义很多的Mapper接口，而且一个Mapper接口中只能有两个类型对象的转换，即Converter中指定的<S, T>泛型。

原本我们可以在一个Mapper接口中定义同一个业务对象的不同JavaBean的转换方法，比如DO，BO，VO等等，现在我们可能需要定义更多的接口了，感觉也没有方便太多。

MapStruct Spring Plus

这是一个第三方插件，在MapStruct Spring Extensions的基础上扩展而来，具体使用可以参考Github上的README：https://github.com/ZhaoRd/mapstruct-spring-plus，或者这篇文章：https://www.jianshu.com/p/48484d2398f1

这个框架解决了需要定义一堆Mapper接口的麻烦，只需要在对象上加注解即可，如：@AutoMap(targetType = UserVO.class)

非常优雅了，不过对于字段转换比较复杂，需要自定义方法的情况来说，就有点麻烦了，你还是需要单独定义一个Mapper接口，然后在@AutoMap使用uses来引用，这就不怎么方便了。

而且这还会导致转换方法比较分散（原本都定义在了Mapper接口中），管理上会麻烦些。另外，这个第三方的插件，后期是否能继续维护，是否存在什么Bug，也是未知的，在成熟的商业项目上引入第三方依赖是个需要慎重考虑的问题。

结语

感谢你看到这里，到这基本上也介绍完了MapStruct，以及常用的方法。MapStruct提供了一种编写高效、性能优异的对象拷贝方式，虽然一般来说系统的性能瓶颈也不会在这，但技多不压身，多了解一个工具，总是有些好处滴！

MapStruct还有很多其他功能，受限于篇幅这里就不一一介绍了，而且使用频率也不高，等有需要的时候再去查资料也不迟。

最后，如果本文有任何错误和不足还请不吝指正！

参考

官方文档：https://mapstruct.org/documentation/stable/reference/html/
官方文档：https://mapstruct.org/documentation/spring-extensions/reference/html/
微信文章：https://mp.weixin.qq.com/s/ayG1S7CE8ToQjDRQAV3o7w
微信文章：https://mp.weixin.qq.com/s/XrmchQUiKcQ9ooteq-6ZlQ
简书：https://www.jianshu.com/p/48484d2398f1
MapStruct 使用手册：https://mofan212.gitee.io/posts/MapStruct-User-Manual/
https://github.com/ZhaoRd/mapstruct-spring-plus
https://github.com/mapstruct/mapstruct-examples