玩转MapStruct,学习就是了

刺骨的言语ヽ痛彻心扉 2024-05-23 22:18 40阅读 0赞

## 玩转MapStruct,学习就是了 ##

### 玩转MapStruct,手把手带你学会！ ###

*  在平时CRUD的工作中，经常需要做PO、VO、DTO之间的转换。简单的对象转换，使用BeanUtils基本上是够了，但是复杂的转换，如果使用它的话又得写一堆Getter、Setter方法了。BeanUtils 就是一个大老粗，只能同属性映射，或者在属性相同的情况下，允许被映射的对象属性少；但当遇到被映射的属性数据类型被修改或者被映射的字段名被修改，则会导致映射失败。而 mapstruct 就是一个巧媳妇儿了，她心思细腻，把我们可能会遇到的情况都给考虑到了，所以今天给大家推荐一款对象自动映射工具MapStruct，接下来我们一起学习这个吧！

#### 关于BeanUtils ####

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

#### 什么是MapStruct？ ####

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

#### 如何使用MapStruct? ####

##### 引入MapStruct依赖 #####

*      <lombok.version>1.18.12</lombok.version>
          <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>

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

*      /**
         * @author JavaAlliance
         * @version 1.0
         */
        @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;//性别
        }

##### 创建VO对象 #####

*      /**
         * @author JavaAlliance
         * @version 1.0
         */
        @Data
        @NoArgsConstructor
        @AllArgsConstructor
        @Accessors(chain = true)
        @EqualsAndHashCode(callSuper = false)
        public class UserVo {
            private Long id ;//用户id
            private String userName;//用户名
            private String password; //密码
            //与PO类型不同的属性
            private Date birthday;//生日
            //与PO名称不同的属性
            private String telNumber;//电话号码
            private String email; //邮箱
            private String idCardNo;//身份证号
            private String icon; //头像
            private Integer gender;//性别
        }
 *  那我们现在要做的就是需要将`User`对象转换为`UserVo`对象；

##### 创建映射接口 #####

*  （目的：实现同名同类型属性、不同名称属性、不同类型属性的映射；）
 *      @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);
        }

##### 效果演示 #####

*      @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！

##### MapStruct实现原理 #####

*  其实MapStruct的实现原理很简单，就是根据我们在Mapper接口中使用的`@Mapper`和`@Mapping`等注解，在运行时生成接口的实现类，我们可以打开项目的`target`目录看下；
 *  ![外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传][20230724024159.png_origin_url_C_3A_5CUsers_5Cquyanliang_5CAppData_5CRoaming_5CTypora_5Ctypora-user-images_5C1710892632636.png_pos_id_img-Hr5vVUgI-1710893081726]
 *  下面是MapStruct为`UserMapper`生成好的对象映射代码，可以和手写Getter、Setter说再见了！
 *      public class UserMapperImpl implements UserMapper {
            public UserMapperImpl() {
            }
        
              public UserVo convertToVo(User user) {
                if (user == null) {
                    return null;
                } else {
                    UserVo userVo = new UserVo();
                    userVo.setTelNumber(user.getTel());
                    if (user.getBirthday() != null) {
                        userVo.setBirthday((new SimpleDateFormat("yyyy-MM-dd")).format(user.getBirthday()));
                    }
        
                    if (user.getId() != null) {
                        userVo.setId(user.getId().longValue());
                    }
        
                    userVo.setUserName(user.getUserName());
                    userVo.setPassword(user.getPassword());
                    userVo.setEmail(user.getEmail());
                    userVo.setIdCardNo(user.getIdCardNo());
                    userVo.setIcon(user.getIcon());
                    userVo.setGender(user.getGender());
                    return userVo;
                }
            }
        }

##### 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);
        
        }
 *  在Controller中创建测试接口，直接通过Mapper接口中的`INSTANCE`实例调用转换方法`toVoList`；
 *      @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":"小张"}]
 *  可见集合映射完全OK

##### 子集和映射 #####

*  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);
            }
        }
 *  打印结果：
 *      {"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":"小慕"}}
 *  从运行结果来看，可以发现子对象属性已经被转换了。 Product对象中count字段的值映射到ProductVo的number字段上了，完全OK

##### 合并映射 #####

*  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中去了。

#### MapStruct的进阶玩法 ####

*  通过上面的基本使用，大家已经可以玩转MapStruct了，下面我们再来介绍一些进阶的用法。

##### 使用Spring依赖注入 #####

*  上面的例子我们都是通过Mapper接口中的INSTANCE实例来调用方法的，在Spring中我们也是可以使用依赖注入的。
 *  想要使用依赖注入，我们只要将@Mapper注解的componentModel参数设置为spring即可，这样在生成接口实现类时，MapperStruct会为其添加@Component注解； （注意：这些mapper文件不要被mybatis的MapScan给扫包扫到了，不然生成的代理对象就是mybatis代理的对象，而不是mapstruct代理的对象了，所以一定要注意）
 *      @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":"小慕"}

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

*  使用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"}

##### 在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"}

##### 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位了

[20230724024159.png_origin_url_C_3A_5CUsers_5Cquyanliang_5CAppData_5CRoaming_5CTypora_5Ctypora-user-images_5C1710892632636.png_pos_id_img-Hr5vVUgI-1710893081726]: https://image.dandelioncloud.cn/pgy_files/images/2024/05/23/33fbbc18fd2e4dd9af5f9a0f8b042726.png