【开发规范】Mapstruct 转换器使用教程

一、对象转化

在业务应用中，我们的代码结构往往是多层次的，不同层次之间经常涉及到对象的转化，虽然很简单，但实际上繁琐且容易出错。

• 反例 1（手动编写方法进行 set）：

public class UserConverter {

    public static UserDTO toDTO(UserDO userDO) {
        UserDTO userDTO = new UserDTO();
        userDTO.setAge(userDO.getAge());
        // 问题 1: 自己赋值给自己
        userDTO.setName(userDTO.getName());
        return userDTO;
    }

    @Data
    public static class UserDO {
        private String name;
        private Integer age;
        // 问题 2: 新增字段未赋值
        private String address;
    }

    @Data
    public static class UserDTO {
        private String name;
        private Integer age;
    }
}

• 反例2（使用copyProperties）：

public class UserBeanCopyConvert {

    public UserDTO toDTO(UserDO userDO) {
        UserDTO userDTO = new UserDTO();
        // 用反射复制不同类型对象.
        // 1. 重构不友好, 当我要删除或修改 UserDO 的字段时, 无法得知该字段是否通过反射被其他字段依赖
        BeanUtils.copyProperties(userDO, userDTO);
        return userDTO;
    }
}

二、推荐使用 MapStruct

Mapstruct 使用编译期代码生成技术，根据注解、入参、出参自动生成转化代码，并且支持各种高级特性，比如：

1. 未映射字段的处理策略，在编译期发现映射问题；
2. 复用工具，方便字段类型转化；
3. 生成 Spring Component 注解，通过 spring 管理；
4. 等等其他特性；

// 注意此处的 Mapper 是 org.mapstruct.Mapper 包下的
@Mapper(
    componentModel = "spring",
    unmappedSourcePolicy = ReportingPolicy.ERROR,
    unmappedTargetPolicy = ReportingPolicy.ERROR,
    // convert 逻辑依赖 DateUtil 做日期转化
    uses = DateUtil.class
)
public interface UserConvertor {

    UserDTO toUserDTO(UserDO userDO);

    @Data
    class UserDO {
        private String name;
        private Integer age;
        //private String address;
        private Date birthDay;
    }

    @Data
    class UserDTO {
        private String name;
        private Integer age;
        private String birthDay;
    }

}

public class DateUtil {
    public static String format(Date date) {
        SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd");
        return simpleDateFormat.format(date);
    }
}

使用示例：

@RequiredArgsConstructor
@Component
public class UserService {
    private final UserDao userDao;
    private final UserCovertor userCovertor;

    public UserDTO getUser(String userId){
        UserDO userDO = userDao.getById(userId);
        return userCovertor.toUserDTO(userDO);
    }
}

编译期校验：

生成的代码：

@Generated(
    value = "org.mapstruct.ap.MappingProcessor",
    date = "2023-12-18T20:17:00+0800",
    comments = "version: 1.3.1.Final, compiler: javac, environment: Java 11.0.12 (GraalVM Community)"
)
@Component
public class UserConvertorImpl implements UserConvertor {

    @Override
    public UserDTO toUserDTO(UserDO userDO) {
        if ( userDO == null ) {
            return null;
        }

        UserDTO userDTO = new UserDTO();

        userDTO.setName( userDO.getName() );
        userDTO.setAge( userDO.getAge() );
        userDTO.setBirthDay( DateUtil.format( userDO.getBirthDay() ) );

        return userDTO;
    }
}

三、MapStruct 介绍

3.1 概念

MapStruct 是一个代码生成器，它基于约定优于配置的方法，极大地简化了 Java bean 类型之间的映射实现。
生成的映射代码使用普通的方法调用，因此速度快、类型安全且易于理解。
MapStruct 是一种注释处理器，可插入 Java 编译器，并可用于命令行构建（Maven、Gradle 等）以及您喜欢的集成开发环境。

MapStruct 使用合理的默认设置，但在需要配置或实施特殊行为时，MapStruct 会自动退出。

3.2 特点

1. 配置灵活：MapStruct支持通过配置文件或注解来定义映射规则。开发人员可以根据具体需求选择更适合的配置方式。
2. 集成简单：MapStruct可以与Spring、CDI等常用的Java框架无缝集成。它与其他框架的兼容性良好，使用起来非常方便。
3. 性能优越：MapStruct通过在编译时生成映射代码，避免了运行时的反射操作，从而提升了映射的性能。它生成的映射代码非常高效，可以满足大部分应用场景的性能需求。

3.3 使用场景

1. 数据库中的字段和对接的A部门、B部门的入参字段不一致的情况。
2. 涉及到一些入参和出参值的转换，比如：性别、日期等。

3.4 使用教程

3.4.1 导入依赖

<!--mapStruct依赖-->
<dependency>
  <groupId>org.mapstruct</groupId>
  <artifactId>mapstruct</artifactId>
  <version>1.4.2.Final</version>
</dependency>
<dependency>
  <groupId>org.mapstruct</groupId>
  <artifactId>mapstruct-processor</artifactId>
  <version>1.4.2.Final</version>
  <scope>provided</scope>
</dependency>

3.4.2 编写 Entity 和 DetailInfo

我这块的 Entity 相当于是 DO，DetailInfo 相当于是（DTO）

import com.alibaba.fastjson.JSONObject;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import com.baomidou.mybatisplus.core.handlers.MybatisEnumTypeHandler;
import com.haoma.webpgsqldemo.enums.GenderEnum;
import com.haoma.webpgsqldemo.typehandler.JSONObjectTypeHandler;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.time.LocalDate;
import java.time.LocalDateTime;
import java.util.Date;

/**
 * @author Zoom
 * @Date 2024/4/17
 * @Description 用户详细信息实体类
 * @Version 1.0
 */
@Data
@AllArgsConstructor
@NoArgsConstructor
@TableName(value="test_user", autoResultMap = true)
public class TestUserEntity {

    @TableId(value = "id", type = IdType.AUTO)
    private Integer id;

    private String name;

    private Integer age;

    // 枚举类型
    @TableField(value = "gender", typeHandler = MybatisEnumTypeHandler.class)
    private GenderEnum gender;

    @TableField(value = "address", typeHandler = JSONObjectTypeHandler.class)
    private JSONObject address;

    private String phone;

    private LocalDate createTime;

}

import com.alibaba.fastjson.JSONObject;
import com.haoma.webpgsqldemo.enums.GenderEnum;
import lombok.Data;

import java.util.Date;

/**
 * @Author Zoom
 * @Date 2024/4/17
 * @Description 用户详细信息实体类
 * @Version 1.0
 */
@Data
public class TestUserDetailInfo {

    private Integer id;

    private String name;

    private Integer age;

    private GenderEnum gender;

    private JSONObject address;

    private String phone;

    private String createTime;

}

3.4.3 编写转换器（※）

现在需要实现 Entity 转换成 DetailInfo，我们来编写一个 Convertor

import com.haoma.webpgsqldemo.entity.TestUserDetailInfo;
import com.haoma.webpgsqldemo.entity.TestUserEntity;
import com.haoma.webpgsqldemo.utils.DateUtil;
import org.mapstruct.Mapper;
import org.mapstruct.ReportingPolicy;

/**
 * @Author Zoom
 * @Date 2024/4/17
 * @Description 用户转换器
 * @Version 1.0
 */
@Mapper(
    componentModel = "spring",
    unmappedSourcePolicy = ReportingPolicy.ERROR,
    unmappedTargetPolicy = ReportingPolicy.ERROR,
    uses = DateUtil.class
)
public interface TestUserConvertor {

    TestUserDetailInfo toUserDetailInfo(TestUserEntity userEntity);

}

参数解释：

• componentModel = "spring"：使用 spring 作为组件模型，这意味着 MapStruct 将会生成一个由 Spring 容器管理的实现类。
• unmappedSourcePolicy：设置了为映射源属性的策略，这里设为ERROR表示如果有为映射属性则会报错。
• unmappedTargetPolicy：设置了未映射目标属性的策略，这里设为ERROR表示如果有为映射属性则会报错。
• uses = DateUtil.class：声明了在转换过程中使用的辅助类 DateUtil，进行日期格式化处理。

import java.text.SimpleDateFormat;
import java.time.LocalDate;

/**
 * @Author Zoom
 * @Date 2024/4/17
 * @Description 日期工具类
 * @Version 1.0
 */
public class DateUtil {

    public static String format(LocalDate localDate){
        SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
        return simpleDateFormat.format(localDate);
    }

}

3.4.4 使用转换器

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
import com.haoma.webpgsqldemo.convertor.TestUserConvertor;
import com.haoma.webpgsqldemo.entity.TestUserDetailInfo;
import com.haoma.webpgsqldemo.entity.TestUserEntity;
import com.haoma.webpgsqldemo.mapper.TestUserMapper;
import com.haoma.webpgsqldemo.service.TestUserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

/**
 * @Author Zoom
 * @Date 2024/4/17
 * @Description 用户服务实现类
 * @Version 1.0
 */
@Service
public class TestUserServiceImpl extends ServiceImpl<TestUserMapper, TestUserEntity> implements TestUserService {

    @Autowired
    private TestUserConvertor testUserConvertor;

    @Override
    public TestUserDetailInfo getUserDetailInfo(TestUserEntity entity) {
        LambdaQueryWrapper<TestUserEntity> queryWrapper = new QueryWrapper<TestUserEntity>().lambda();
        queryWrapper.eq(TestUserEntity::getId, entity.getId());

        if(entity.getGender()!= null){
            queryWrapper.eq(TestUserEntity::getGender, entity.getGender());
        }
        TestUserEntity userEntity = getOne(queryWrapper);
        // 将 UserEntity 转换成 UserDetailInfo
        return testUserConvertor.toUserDetailInfo(userEntity);
    }

}

3.4.5 结果

调用接口测试：

3.4.6 扩展（MapStruct 其他常用参数）

1. componentModel：指映射器的组件模型，常用的取值有：
   1. default：使用默认的组件模型，在编译时生成的 Mapper 实现类是独立的，不依赖于任何外部框架。
   2. spring：使用 Spring 作为组件模型，生成的 Mapper 实现类会被 Spring 容器管理。
   3. cdi：使用 CDI（Contexts and Dependency Injection）作为组件模型。
   4. jsr330：使用 JSR-330 标准实现的组件模型。
2. uses：指定在转换过程中使用的工具类。
3. unmappedSourcePolicy：未映射源属性的策略，可选值包括：
   1. IGNORE：忽略未映射源属性。
   2. WARN：警告为映射源属性。
   3. ERROR：报错，未映射源属性会触发编译错误。
4. unmappedTargetPolicy: 未映射目标属性的策略，可选值和含义和unmappedSourcePolicy类似。
5. mapping: 可以通过@Mapping注解进行自定义映射，包括属性名映射、表达式映射等。
6. implementationName: 指定生成的实现类的名称。