MapStruct：工具使用

yubin1285570923

已于 2022-06-16 00:49:55 修改

阅读量1.1k

点赞数

分类专栏： Java 文章标签： java java-ee spring

于 2022-06-16 00:30:03 首次发布

本文链接：https://blog.csdn.net/yubin1285570923/article/details/125307488

版权

Java 专栏收录该内容

13 篇文章 0 订阅

订阅专栏

一、什么是MapStruct

平时我经常使用Hutool中的BeanUtil类来实现对象转换，用多了之后就发现有些缺点：

对象属性映射使用反射来实现，性能比较低；
对于不同名称或不同类型的属性无法转换，还得单独写Getter、Setter方法；
对于嵌套的子对象也需要转换的情况，也得自行处理；
集合对象转换时，得使用循环，一个个拷贝。
对于这些不足，MapStruct都能解决，不愧为一款功能强大的对象映射工具！

MapStruct是一款基于Java注解的对象属性映射工具，使用的时候我们只要在接口中定义好对象属性映射规则，它就能自动生成映射实现类，不使用反射，性能优秀，能实现各种复杂映射。

二、如何使用

mapstruct官网

1、引入MapStruct依赖

<mapstruct.version>1.4.2.Final</mapstruct.version>

		<dependency>
			<groupId>org.mapstruct</groupId>
			<artifactId>mapstruct</artifactId>
			<version>${mapstruct.version}</version>
		</dependency>
		<dependency>
			<groupId>org.mapstruct</groupId>
			<artifactId>mapstruct-processor</artifactId>
			<version>${mapstruct.version}</version>
			<scope>compile</scope>
		</dependency>

2、创建我们所需要的案例实体类

@Data
@NoArgsConstructor
@AllArgsConstructor
@EqualsAndHashCode(callSuper = false)
@Accessors(chain = true)
public class User {
    private Integer id ;//用户id
    private String userName;//用户名
    private String password; //密码
    private Date birthday;//生日
    private String tel;//电话号码
    private String email; //邮箱
    private String idCardNo;//身份证号
    private String icon; //头像
    private Integer gender;//性别
}

3、创建VO对象

@Data
@NoArgsConstructor
@AllArgsConstructor
@Accessors(chain = true)
@EqualsAndHashCode(callSuper = false)
public class UserVo {
    private Long id ;//用户id
    private String userName;//用户名
    private String password; //密码
    //与PO类型不同的属性
    private String birthday;//生日
    //与PO名称不同的属性
    private String telNumber;//电话号码
    private String email; //邮箱
    private String idCardNo;//身份证号
    private String icon; //头像
    private Integer gender;//性别
}

4、创建映射接口

（目的：实现同名同类型属性、不同名称属性、不同类型属性的映射；）

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

    @Mapping(source = "tel",target = "telNumber")
    @Mapping(source = "birthday",target = "birthday",dateFormat = "yyyy-MM-dd")
    UserVo convertToVo(User user);
}

5、效果演示

@RestController
@RequestMapping("/user")
public class UserController {

    @GetMapping("/mapStructToVo")
    public Result mapStructToVo() {
        User user = new User();
        user.setId(1).setEmail("1964327885@qq.com").setUserName("小慕").setBirthday(new Date()).setTel("18772563087");
        UserVo userVo = userMapper.convertToVo(user);
        System.out.println(JSON.toJSONString(userVo));
        return Result.success(userVo);
    }
}

{"birthday":"2021-11-26","email":"1964327885@qq.com","id":1,"telNumber":"18772563087","userName":"小慕"}

正如运行效果所示，User对象中的tel字段的值被映射到UserVo对象的telNumber字段上了，User对象中的Date类型的birthday被映射到UserVo中的String类型的birthday上了，完全OK！

6、MapStruct实现原理

其实MapStruct的实现原理很简单，就是根据我们在Mapper接口中使用的@Mapper和@Mapping等注解，在运行时生成接口的实现类，我们可以打开项目的target目录看下；
在这里插入图片描述

7、MapStruct对集合进行映射

MapStruct也提供了集合映射的功能，可以直接将一个PO列表转换为一个VO列表，再也不用一个个对象转换了！
在UserMapper接口中添加toVoList方法用于列表转换；

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

 @Mapping(source = "tel", target = "telNumber")
 @Mapping(source = "birthday", target = "birthday", dateFormat = "yyyy-MM-dd")
 List<UserVo> toVoList(List<User> list);

}

测试：

 @RestController
@RequestMapping("/user")
public class UserController {
 @Autowired
    UserMapper userMapper;

 @GetMapping("/mapStructToList")
 public Result mapStructToList() {
 User user1 = new User().setId(1).setEmail("1964327885@qq.com").setUserName("小慕")
                .setBirthday(new Date()).setTel("18772563087");
 User user2 = new User().setId(2).setEmail("1664687767@qq.com").setUserName("小王")
                .setBirthday(new Date()).setTel("13455332134");
 User user3 = new User().setId(3).setEmail("1323243433@qq.com").setUserName("小张")
                .setBirthday(new Date()).setTel("1534323232");
 List<User> userList = new ArrayList<>();
   userList.add(user1);
   userList.add(user2);
   userList.add(user3);
   List<UserVo> userVoList = UserMapper.INSTANCE.toVoList(userList);
   System.out.println(JSON.toJSONString(userVoList));
 return Result.success(userVoList);
    }
}

打印结果:
[{“birthday”:“2021-11-24”,“email”:“1964327885@qq.com”,“id”:1,“telNumber”:“18772563087”,“userName”:“小慕”},{“birthday”:“2021-11-24”,“email”:“1664687767@qq.com”,“id”:2,“telNumber”:“13455332134”,“userName”:“小王”},{“birthday”:“2021-11-24”,“email”:“1323243433@qq.com”,“id”:3,“telNumber”:“1534323232”,“userName”:“小张”}]

8、子集和映射

MapStruct对于对象中包含子对象也需要转换的情况也是有所支持的。

例如我们有一个订单PO对象Order，嵌套有User和Product对象；

@Data
@EqualsAndHashCode(callSuper = false)
public class Order {
    private Long id;
    private String orderNo;//订单号
    private Date createTime;
    private String receiverAddress; //收货地址
    private User user;//订单所属的用户
    private List<Product> productList; //商品集合
}

@Data
@Accessors(chain = true)
@EqualsAndHashCode(callSuper = false)
public class Product {
    private Long id;
    private String productSn;
    private String name;
    private String subTitle;
    private String brandName;
    private BigDecimal price;
    private Integer count;//商品数量
    private Date createTime;
}

我们需要转换为OrderDo对象，OrderDo中包含UserVo和ProductVo两个子对象同样需要转换

@Data
@EqualsAndHashCode(callSuper = false)
public class OrderVo {
    private Long id;
    private String orderNo; //订单号
    private Date createTime;
    private String receiverAddress; //收货地址
    //子对象映射Dto
    private UserVo userVo;//订单所属的用户
    //子对象数组映射Dto
    private List<ProductVo> productVoList; //商品集合
}

@Data
@EqualsAndHashCode(callSuper = false)
public class ProductVo {
    //使用常量
    private Long id;
    //使用表达式生成属性
    private String productSn;
    private String name;
    private String subTitle;
    private String brandName;
    private BigDecimal price;
    //使用默认值
    private Integer number;//商品数量
    private Date createTime;
}

我们只需要创建一个Mapper接口，然后通过使用uses将子对象的转换Mapper注入进来，然后通过@Mapping设置好属性映射规则即可

@Mapper(uses = {UserMapper.class,ProductMapper.class})
public interface OrderMapper {
    OrderMapper INSTANCE = Mappers.getMapper(OrderMapper.class);

    @Mapping(source = "user",target = "userVo")
    @Mapping(source = "productList",target = "productVoList")
    OrderVo convertToVo(Order order);
}

@Mapper(imports = {UUID.class})
public interface ProductMapper {
    ProductMapper INSTANCE = Mappers.getMapper(ProductMapper.class);

    @Mapping(target = "id",constant = "-1L")
    @Mapping(source = "count",target = "number",defaultValue = "1")
    @Mapping(target = "productSn",expression = "java(UUID.randomUUID().toString())")
    ProductVo convertToVo(Product product);
}

接下来在Controller中创建测试接口，直接通过Mapper中的INSTANCE实例调用转换方法toDto

@RestController
@RequestMapping("/order")
public class OrderController {
    @ApiOperation(value = "子对象映射")
    @GetMapping("/mapStructToSubVo")
    public Result mapStructToSubVo() {
        //创建一个user对象
        User user = new User();
        user.setId(1).setEmail("1964327885@qq.com").setUserName("小慕")
            .setBirthday(new Date()).setTel("18772563087");
        //创建productList
        List<Product> productList = new ArrayList<>();
        productList.add(new Product().setCount(3));
        productList.add(new Product().setCount(7));
        Order order = new Order();
        order.setUser(user).setProductList(productList);
        OrderVo orderVo = OrderMapper.INSTANCE.convertToVo(order);
        System.out.println(JSON.toJSONString(orderVo));
        return Result.success(orderVo);
    }
}

打印结果：
从运行结果来看，可以发现子对象属性已经被转换了。 Product对象中count字段的值映射到ProductVo的number字段上了，完全OK

{"productVoList":[{"id":-1,"number":3,"productSn":"a27c7f07-7f5b-45e1-ae99-cea741b35d85"},{"id":-1,"number":7,"productSn":"75012846-bdc2-4dc1-849b-47442bba70c8"}],"userVo":{"birthday":"2021-11-24","email":"1964327885@qq.com","id":1,"telNumber":"18772563087","userName":"小慕"}}

9、合并映射

MapStruct也支持把多个对象属性映射到一个对象中去。

例如这里把User和Order的部分属性映射到UserOrderDto中去；

@Data
@EqualsAndHashCode(callSuper = false)
public class UserOrderVo {
    private Long id ;//用户id
    private String userName;//用户名
    private String password; //密码
    //与PO类型不同的属性
    private String birthday;//生日
    //与PO名称不同的属性
    private String telNumber;//电话号码
    private String email;
    private String idCardNo;//身份证号
    private String icon; //头像
    private Integer gender;//性别

    private String orderNo; //订单号
    private String receiverAddress; //用户收货地址
}

然后在Mapper中添加toUserOrderVo方法，这里需要注意的是由于参数中具有两个属性，需要通过参数名称.属性的名称来指定source来防止冲突（这两个参数中都有id属性）;

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

    @Mapping(source = "user.tel",target = "telNumber")
    @Mapping(source = "user.birthday",target = "birthday",dateFormat = "yyyy-MM-dd")
    @Mapping(source = "user.id",target = "id")
    @Mapping(source = "order.orderNo", target = "orderNo")
    @Mapping(source = "order.receiverAddress", target = "receiverAddress")
    UserOrderVo toUserOrderVo(User user, Order order); 
}

接下来在Controller中创建测试接口，直接通过Mapper中的INSTANCE实例调用转换方法toUserOrderDto

@ApiOperation(value = "组合映射")
@GetMapping("/compositeMapping")
public Result compositeMapping() {
//新建一个user对象
User user = new User();
user.setId(1).setEmail("1964327885@qq.com").setUserName("小慕")
.setBirthday(new Date()).setTel("18772563087");
//新建一个Order对象
Order order = new Order();
order.setReceiverAddress("湖北省武汉市洪山区").setOrderNo("323121213232");
UserOrderVo userOrderVo = UserMapper.INSTANCE.toUserOrderVo(user,order);
System.out.println(JSON.toJSONString(userOrderVo));
return Result.success(userOrderVo);
}

打印结果：

{"birthday":"2021-11-24","email":"1964327885@qq.com","id":1,"orderNo":"323121213232","receiverAddress":"湖北省武汉市洪山区","telNumber":"18772563087","userName":"小慕"}

从打印结果来看，可以发现User和Order中的属性已经被映射到userOrderVo中去了。

3、MapStruct的进阶玩法

1、使用Spring依赖注入

上面的例子我们都是通过Mapper接口中的INSTANCE实例来调用方法的，在Spring中我们也是可以使用依赖注入的。

想要使用依赖注入，我们只要将@Mapper注解的componentModel参数设置为spring即可，这样在生成接口实现类时，MapperStruct会为其添加@Component注解；

@Mapper(componentModel = "spring")  //使用spring依赖注入
public interface UserMapper {
    // UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);

    @Mapping(source = "tel", target = "telNumber")
    @Mapping(source = "birthday", target = "birthday", dateFormat = "yyyy-MM-dd")
    UserVo convertToVo(User user);
  }

接下来在Controller中使用@Autowired注解注入即可使用；

@RestController
@RequestMapping("/user")
public class UserController {
    @Autowired
    UserMapper userMapper;

    @GetMapping("/mapStructToVo")
    public Result mapStructToVo() {
        User user = new User();
        user.setId(1).setEmail("1964327885@qq.com").setUserName("小慕").setBirthday(new Date()).setTel("18772563087");
        UserVo userVo = userMapper.convertToVo(user);
        System.out.println(JSON.toJSONString(userVo));
        return Result.success(userVo);
    }
}

结果：

{"birthday":"2021-11-24",
 "email":"1964327885@qq.com","id":1,"telNumber":"18772563087","userName":"小慕"}

2、使用常量、默认值和表达式

使用MapStruct映射属性时，我们可以设置属性为常量或者默认值，也可以通过Java中的方法编写表达式来自动生成属性。

@Data
@Accessors(chain = true)
@EqualsAndHashCode(callSuper = false)
public class Product {
    private Long id;
    private String productSn;
    private String name;
    private String subTitle;
    private String brandName;
    private BigDecimal price;
    private Integer count;//商品数量
    private Date createTime;
}

我们想把Product转换为ProductVo对象，id属性设置为常量，count设置默认值为1，productSn设置为UUID生成；

@Data
@EqualsAndHashCode(callSuper = false)
public class ProductVo {
    //使用常量
    private Long id;
    //使用表达式生成属性
    private String productSn;
    private String name;
    private String subTitle;
    private String brandName;
    private BigDecimal price;
    //使用默认值
    private Integer number;//商品数量

    private Date createTime;
}

创建ProductMapper接口，通过@Mapping注解中的constant、defaultValue、expression设置好映射规则；

@Mapper(imports = {UUID.class})
public interface ProductMapper {
    ProductMapper INSTANCE = Mappers.getMapper(ProductMapper.class);

    @Mapping(target = "id",constant = "-1L")  //给转换后的productVo的id字段设置为常量-1
    @Mapping(source = "count",target = "number",defaultValue = "1")
    @Mapping(target = "productSn",expression = "java(UUID.randomUUID().toString())")
    ProductVo convertToVo(Product product);
}

接下来在Controller中创建测试接口，直接通过接口中的INSTANCE实例调用转换方法convertToVo；

@RestController
@RequestMapping("/product")
public class ProductController {
    @GetMapping("/defaultMapping")
    public Result defaultMapping() {
        Product product = new Product();
        product.setId(100L);
        product.setCount(null);
        ProductVo productVo = ProductMapper.INSTANCE.convertToVo(product);
        System.out.println(JSON.toJSONString(productVo));
        return Result.success(productVo);
    }
}

结果

{"id":-1,"number":1,"productSn":"5673a313-fde6-450c-8c55-f8242b57af2a"}

3、在MapStruct映射前后进行自定义切面处理

MapStruct也支持在映射前后做一些自定义操作，类似Spring的AOP中的切面。

由于此时我们需要创建自定义处理方法，创建一个抽象类ProductRoundMapper，通过@BeforeMapping注解自定义映射前操作，通过@AfterMapping注解自定义映射后操作；

@Mapper(imports = {UUID.class})
public abstract class ProductRoundMapper {
    public static ProductRoundMapper INSTANCE = Mappers.getMapper(ProductRoundMapper.class);

    @Mapping(target = "id",constant = "-1L")
    @Mapping(source = "count",target = "number",defaultValue = "1")
    @Mapping(target = "productSn",expression = "java(UUID.randomUUID().toString())")
    public abstract ProductVo convertToVo(Product product);

    @BeforeMapping
    public void beforeMapping(Product product){
        //映射前当price<0时设置为0
        if(product.getPrice().compareTo(BigDecimal.ZERO)<0){
            product.setPrice(BigDecimal.ZERO);
        }
    }

    @AfterMapping
    public void afterMapping(@MappingTarget ProductVo productVo){
        //映射后设置当前时间为createTime
        productVo.setCreateTime(new Date());
    }
}

接下来在Controller中创建测试接口，直接通过Mapper中的INSTANCE实例调用转换方法convertToVo；

@RestController
@RequestMapping("/product")
public class ProductController {
    @GetMapping("/defaultMapping")
    public Result defaultMapping() {
        Product product = new Product();
        product.setId(100L);
        product.setCount(null);
        product.setPrice(new BigDecimal(-100) );
        ProductVo productVo = ProductRoundMapper.INSTANCE.convertToVo(product);
        System.out.println(JSON.toJSONStringWithDateFormat(productVo,"yyyy-MM-dd HH:mm:ss"));
        return Result.success(productVo);
    }
}

结果“

{"createTime":"2021-11-26 11:26:11","id":-1,"number":1,"price":0,"productSn":"cf387cf1-8750-4f5a-adaa-2037ac7d719a"}

4、MapStruct里的验证器

我们先创建一个验证类，当Userd对象的tel超过11位时就抛出异常；

public class UserValidator {
    public String validatePrice(String tel) throws Exception {
        if(StringUtils.isNotBlank(tel)&&tel.length()>11){
            throw new Exception("手机号位数超过11位了");
        }
        return tel;
    }
}

之后我们通过@Mapper注解的uses属性运用验证类；

@Mapper(uses = {UserValidator.class},imports = {UUID.class})
public interface UserExceptionMapper {
    UserExceptionMapper INSTANCE = Mappers.getMapper(UserExceptionMapper.class);

    @Mapping(source = "tel", target = "telNumber")
    @Mapping(source = "birthday", target = "birthday", dateFormat = "yyyy-MM-dd")
    UserVo convertToVo(User user) throws Exception;
}

最后我们在Controller层验证下效果
@RestController
@RequestMapping("/user")
public class UserController {

@GetMapping("/mapStructToVo")
public Result mapStructToVo() {
User user = new User();
user.setId(1).setEmail("1964327885@qq.com").setUserName("小慕").setBirthday(new Date()).setTel("18772563087");
try {
UserVo userVo = UserExceptionMapper.INSTANCE.convertToVo(user);
}catch (Exception e) {
System.out.println(e.getMessage());
}
return Result.success("");
}
}

结果：手机号位数超过11位了

5、可以在mapper接口中定义默认方法和静态方法，使用@Named 区分区分匹配

当使用 Java 8 或更高版本时，您可以直接在映射器接口中实现自定义方法作为默认方法。如果参数和返回类型匹配，生成的代码将调用默认方法。

与users 引用的外部类一样的效果，source中的属性会匹配到对用的方法执行。

@Mapper
public interface CarMapper {

    @Mapping(...)
    ...
    CarDto carToCarDto(Car car);

    default PersonDto personToPersonDto(Person person) {
        //hand-written mapping logic
    }
}

@Mapper
public interface MovieMapper {

     @Mapping( target = "category", qualifiedByName = "CategoryToString", defaultValue = "DEFAULT" )
     GermanRelease toGerman( OriginalRelease movies );

     @Named("CategoryToString")
     default String defaultValueForQualifier(Category cat) {
         // some mapping logic
     }
}

MapStruct 生成的类实现了该方法carToCarDto()。中生成的代码会在映射属性时carToCarDto()调用手动实现的方法。personToPersonDto()

映射器也可以以抽象类而不是接口的形式定义，并直接在映射器类中实现自定义方法。在这种情况下，MapStruct 将生成抽象类的扩展，其中包含所有抽象方法的实现。与声明默认方法相比，这种方法的一个优点是可以在映射器类中声明附加字段。

@Mapper
public abstract class CarMapper {

    @Mapping(...)
    ...
    public abstract CarDto carToCarDto(Car car);

    public PersonDto personToPersonDto(Person person) {
        //hand-written mapping logic
    }
}

6、灵活应用表达式expression

@Mapper(componentModel = "spring")
public interface DelegateInforConveter {

    @Mapping(source = "fileList", target = "dispatchFile")
    @Mapping(source = "applicantDate", target = "applicantDate", dateFormat = "yyyy-MM-dd")
    @Mapping(source = "expectFinishDate", target = "expectFinishDate", dateFormat = "yyyy-MM-dd")
    TblDelegateInformation convert(ReceiveOperaMainReq receiveOperaMainReq);

    //
    //@Mapping(target = "dispatchFileList", expression = "java(new com.sip.pwpm.application.core.service.detective.handle.FlowApproveService().processAttachToList(delegateInformation.getDispatchFile()))")
    //@Mapping(target = "sketchFileList",expression = "java(new com.sip.pwpm.application.core.service.detective.handle.FlowApproveService().processAttachToList(projectInformation.getSketchFile()))")
    @Mapping(target = "dispatchFileList", expression = "java(DelegateInforConveter.processAttachToList(delegateInformation.getDispatchFile()))")
    @Mapping(target = "sketchFileList", expression = "java(DelegateInforConveter.processAttachToList(projectInformation.getSketchFile()))")
    ConfessdetailResp conver(TblDelegateInformation delegateInformation, TblProjectInformation projectInformation);


    default String map(List<FileInfoVo> infoVoList) {
        return JSON.toJSONString(infoVoList);
    }

    @Named(value = "toJson")
    static String processAttachToJson(List<FileInfoVo> imgs) {
        return JSON.toJSONString(imgs);
    }

    @Named(value = "toList")
    static List<FileInfoVo> processAttachToList(String imgs) {
        return (org.apache.commons.lang.StringUtils.isEmpty(imgs) ? new ArrayList<>() : JSON.parseArray(imgs, FileInfoVo.class));
    }

}

7、更新现有的 bean 实例

在某些情况下，您需要不创建目标类型的新实例而是更新该类型的现有实例的映射。这种映射可以通过为目标对象添加一个参数并用标记这个参数来实现@MappingTarget。下面显示了一个示例：

@Mapper
public interface CarMapper {

    void updateCarFromDto(CarDto carDto, @MappingTarget Car car);
}

该方法的生成代码将使用给定对象的属性updateCarFromDto()更新传递的实例。可能只有一个参数被标记为映射目标。你也可以将方法的返回类型设置为目标参数的类型，这将导致生成的实现更新传递的映射目标并返回它。这允许流畅地调用映射方法