优雅使用 MapStruct 进行类复制

前言

在项目中，常常会遇到从数据库读取数据后不能直接返回给前端展示的情况，因为还需要对字段进行加工，比如去除时间戳记录、隐藏敏感数据等。传统的处理方式是创建一个新类，然后编写大量的 get/set 方法进行赋值，若字段很多，这无疑是一场噩梦，而且还容易出现遗漏的情况。

我们都清楚，随着工程日益成熟，模块划分会越发细致。实体类通常存放在 domain 中，但最好不要让 domain 工程被其他工程依赖。所以，当其他工程需要获取实体类数据时，就需要在各自工程中编写 model。自定义 model 能够根据自身业务需求映射相应的实体属性。如此一来，这个映射工作似乎并不简单。

这个时候，我们可以使用MapStruct，
在企业级应用中，经常需要在不同类型的对象（如 DTO 和 DO、VO 和 PO 等）之间进行转换。MapStruct 通过在编译时基于接口定义生成转换代码，大大简化了这个过程。例如，从一个包含用户注册信息的 DTO 转换为一个用于业务逻辑处理的 DO 时，只需要定义一个 MapStruct 接口。

引入依赖

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <java.version>17</java.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <lombok.version>1.18.34</lombok.version>
    <mapstruct.version>1.6.2</mapstruct.version>
</properties>

<dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.13.2</version>
      <scope>test</scope>
    </dependency>
    
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <version>${lombok.version}</version>
    </dependency>
    
    <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>provider</scope>
    </dependency>

</dependencies>

`org.mapstruct:mapstruct`

这是MapStruct的核心库。它包含了用于定义映射接口的注解（如@Mapper、@Mapping等）以及在运行时执行映射操作所需的类型和接口。
开发人员在Java代码中使用这些注解来定义对象之间的映射关系。例如，在不同的领域对象（Domain Object）、数据传输对象（Data Transfer Object）、视图对象（View Object）等之间的转换映射。这个库提供了基本的框架，使得可以按照声明式的方式指定对象属性如何从一个对象映射到另一个对象。
当执行映射操作时（例如，通过调用由MapStruct生成的映射器实例的映射方法），这个库中的代码会协调映射过程，根据定义的映射规则进行数据的转换。

`org.mapstruct:mapstruct - processor`

这个依赖是MapStruct的注解处理器（Annotation Processor）。在Java编译过程中，它会查找带有MapStruct注解（来自org.mapstruct:mapstruct库）的接口或抽象类。
一旦找到这样的接口或抽象类，它会根据定义的映射关系（通过@Mapper、@Mapping等注解）生成具体的映射实现类。这个生成过程是在编译时进行的，生成的代码会被编译到最终的字节码中。
例如，如果有一个定义了从SourceObject到TargetObject映射关系的@Mapper接口，mapstruct - processor会生成一个实现该接口的类，这个类包含了将SourceObject的属性值按照指定规则赋给TargetObject属性的具体代码。这里的<scope>provider</scope>表示该依赖是一个提供运行时环境所需的组件，主要用于在编译时提供代码生成功能。

定义实体

定义两个实体，字段上略微有些差别

import java.util.Date;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {
    private long id;
    private String name;
    private int age;
    private String password;
    private Date createTime;
}


import lombok.Data;

@Data
public class UserVO {
    private Long id;
    private String name;
    private Integer age;
    private String code;
    private String hello;
    private String createTime;
}

定义转换的mapper

如果是spring项目，用@Mapper(componentModel = "spring")，生成的实现类上面会自动添加一个@Component注解，可以通过Spring的 @Autowired方式进行注入

package com.zxy.demo;

import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.factory.Mappers;

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

    static String hello(User user) {
        return "hello " + user.getName();
    }

    @Mapping(target = "createTime", source = "createTime", dateFormat = "yyyy-MM-dd HH:mm:ss")
    @Mapping(target = "code", expression="java(\"xx-\" + user.getId())")
    @Mapping(target = "hello", expression = "java(UserMapper.hello(user))")
    UserVO toUserVO(User user);

}

如果所有的字段都一样，用@Mappings({})。
不一样的用target+source，需要特殊处理的可以用expression。

在 MapStruct 中，expression是一个强大的功能，用于在对象映射过程中执行自定义的表达式。它允许开发人员在映射规则中使用 Java 表达式来处理复杂的映射逻辑，而不仅仅是简单的属性到属性的映射。

这在源对象和目标对象的属性之间存在复杂关系，或者需要进行额外的计算、逻辑判断等情况时非常有用。

来个单测运行一下

package  com.zxy.demo;

import java.util.Date;

import org.junit.Assert;
import org.junit.Test;

public class UserTest {

    @Test
    public void ok() {
        User u = new User();
        u.setId(1);
        u.setAge(10);
        u.setName("zxy");
        u.setPassword("123456");
        u.setCreateTime(new Date());

        Assert.assertEquals(10, u.getAge());
        Assert.assertEquals("zxy", u.getName());

        System.out.println(new User(1, "zxy", 12, "123456", new Date()));

        UserVO vo = UserMapper.INSTANCE.toUserVO(u);
        System.out.println("vo: "+vo);
        Assert.assertEquals("zxy", vo.getName());
        Assert.assertEquals("xx-1", vo.getCode());
        Assert.assertEquals("hello zxy", vo.getHello());
    }
}

简单看一下生成的代码

UserMapperImpl.java

 // Source code is unavailable, and was generated by the Fernflower decompiler.
package com.zxy.demo;

import java.text.SimpleDateFormat;

public class UserMapperImpl implements UserMapper {
   public UserVO toUserVO(User user) {
      if (user == null) {
         return null;
      } else {
         UserVO userVO = new UserVO();
         if (user.getCreateTime() != null) {
            userVO.setCreateTime((new SimpleDateFormat("yyyy-MM-dd HH:mm:ss")).format(user.getCreateTime()));
         }

         userVO.setId(user.getId());
         userVO.setName(user.getName());
         userVO.setAge(user.getAge());
         userVO.setCode("xx-" + user.getId());
         userVO.setHello(UserMapper.hello(user));
         return userVO;
      }
   }
}