序言

本文给大家介绍 MapStruct。

一、问题引入

在我们的日常开发过程中，我们经常会将 VO、DTO、PO …… 等对象相互进行映射。实现的方式可能有以下几种：

1. 自己手动进行转换
2. 利用诸如 Spring 或 Apache 提供的 BeanUtils 等工具类

如果自己手动进行转换，这将会增加开发人员的工作量。如果利用上述的这些工具类通常会存在性能问题（因为这些工具类通常使用的是反射机制）。

二、MapStruct

MapStruct 是一个用于生成类型安全的 bean 映射类的 Java 注解处理器。开发人员通过定义一个映射器接口，该接口声明任何所需的映射方法。在编译过程中，MapStruct 将生成此接口的实现。

三、快速入门

3.1 导入依赖

<dependency><groupId>org.mapstruct</groupId><artifactId>mapstruct</artifactId><version>1.5.5.Final</version>
</dependency><!--此依赖必须位于 Lombok 依赖的下面-->
<dependency><groupId>org.mapstruct</groupId><artifactId>mapstruct-processor</artifactId><version>1.5.5.Final</version>
</dependency>

3.2 定义接口

@Mapper
public interface UserMapper {// 固定写法UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);// 参数是 User 实体类，返回 UserDTOUserDTO userToUserDTO(User user);
}

3.3 使用

@Test
public void test() {User user = new User(1, "zs");// 直接调用定义好的接口方法// User 实体类转换成 UserDTOUserDTO userDTO = UserMapper.INSTANCE.userToUserDTO(user);System.out.println(userDTO);
}

测试效果：

四、映射器

在快速入门的例子中，User 和 UserDTO 的字段都是相对应的。如果需要映射字段是不相同的呢？MapperStruct 提供了映射器可以帮助我们解决这些问题。

4.1 基本映射

@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {private int id;private String name;
}@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserDTO {private int id;private String username;
}

如果我们需要将 User 的 name 字段映射到 username，只需要按如下方式简单的添加一个注解就行了。

@Mapper
public interface UserMapper {UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);// 使用 @Mapping 表示映射关系@Mapping(target = "username", source = "name")UserDTO userToUserDTO(User user);
}

4.2 组合注解

为了能够让开发者更加方便的使用，MapStrut 提供了自定义组合注解的方式。

@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {private int id;private String name;
}@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserDTO {private int id;private String name;private String username;
}

如果我们想要将 User 的 name 都映射到 UserDTO 的 name 和 username，我们可以采用以下的方式：

1. 定义一个组合注解

   	@Retention(RetentionPolicy.CLASS)@Mapping(target = "username", source = "name")public @interface Composition {}
   

2. 使用组合注解

   	@Mapperpublic interface UserMapper {UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);@CompositionUserDTO userToUserDTO(User user);}
   

   组合注解可以达到与直接使用 @Mapping 注解相同的效果：

   

五、映射方法

@Data
@NoArgsConstructor
@AllArgsConstructor
public class User {private int id;private String name;
}@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserDTO {private int id;private String name;private int nameLen;
}

在开发的过程中，有时映射逻辑可能比较复杂。MapStruct 提供的注解映射器可能无法满足。例如：我们需要在映射时将上面 name 的长度映射到 nameLen。
MapStruct 可以使用接口默认方法解决特殊的映射需求。

@Mapper
public interface UserMapper {UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);default UserDTO userToUserDTO(User user) {UserDTO userDTO = new UserDTO();userDTO.setId(user.getId());userDTO.setName(user.getName());userDTO.setNameLen(user.getName().length());return userDTO;}
}

测试效果：

六、装饰器类

上面的映射方法其实就是手动实现映射关系。但是，开发人员可能只想修改几个特殊的字段映射，这时可以利用装饰器类来处理映射。

@Mapper
// 使用装饰器
@DecoratedWith(UserMapperDecorator.class)
public interface UserMapper {UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);UserDTO userToUserDTO(User user);}// 装饰器类
public abstract class UserMapperDecorator implements UserMapper {private final UserMapper delegate;public UserMapperDecorator(UserMapper delegate) {this.delegate = delegate;}@Overridepublic UserDTO userToUserDTO(User user) {UserDTO userDTO = delegate.userToUserDTO(user);// 特殊处理 nameLen 字段映射userDTO.setNameLen(user.getName().length());return userDTO;}
}

七、依赖注入

现在，我们项目的开发一般都是采用的 Spring。MapStruct 提供了更加适合 Spring 的依赖注入方式。

// componentModel 指定使用 Spring 模式
@Mapper(componentModel = MappingConstants.ComponentModel.SPRING)
@DecoratedWith(UserMapperDecorator.class)
public interface UserMapper {UserDTO userToUserDTO(User user);
}public abstract class UserMapperDecorator implements UserMapper {// 装饰器中采用注解获取@Resourceprivate UserMapper delegate;@Overridepublic UserDTO userToUserDTO(User user) {UserDTO userDTO = delegate.userToUserDTO(user);userDTO.setNameLen(user.getName().length());return userDTO;}
}

使用方式：

// 使用注解注入
@Resource
private UserMapper userMapper;@Test
public void test() {User user = new User(1, "zs");UserDTO userDTO = userMapper.userToUserDTO(user);System.out.println(userDTO);
}

八、类型转换

在实体类映射的过程中，我们经常会遇到如下的问题：

@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserDTO {private int id;private String name;// 在 dto 中 status 字段是 boolean 类型private boolean status;
}@Data
@NoArgsConstructor
@AllArgsConstructor
public class UserPO {private int id;private String name;// 在 po 中 status 字段是 status 类型private Integer status;
}

如果需要类型转换，可以通过以下方式处理：

// 新增一个类型映射
// 如果使用了 Spring 模式，则需要注入
@Component
public class IntBooleanMapper {public boolean intToBoolean(int value) {return value == 1;}public int booleanToInt(boolean value) {return value ? 1 : 0;}
}// 使用 uses 指定
@Mapper(componentModel = MappingConstants.ComponentModel.SPRING,uses = {IntBooleanMapper.class})
@DecoratedWith(UserMapperDecorator.class)
public interface UserMapper {UserDTO userToUserDTO(User user);UserDTO UserPOToUserDTO(UserPO userPO);}

测试类型转换：

@Resource
private UserMapper userMapper;@Test
public void test() {UserPO userPO = new UserPO(1, "ZS", 1);UserDTO userDTO = userMapper.UserPOToUserDTO(userPO);System.out.println(userDTO);
}

测试效果：

九、默认值

在 MapStruct 中，还可以指定映射的默认值。

@Mapper(componentModel = MappingConstants.ComponentModel.SPRING)
public interface UserMapper {// 使用 defaultValue 定义默认值为 default// 如果 User 的 name 为 null，那么 UserDTO 的 name 值则为 default@Mapping(target = "name", defaultValue = "default")UserDTO userToUserDTO(User user);}

十、FAQ

1. MapStruct 依赖与 Lombok 依赖可能存在冲突的情况，在引入 MapStruct 相关依赖时要严格安装本文提供的顺序引入。
2. MapStruct 的原理是通过定义的接口，自动帮助开发人员生成映射代码。所以当修改了接口中内容，若没有立即生效则可能需要使用 mvn clean 或 mvn compile 等命令清理一下自动生成的旧版本代码。

往期推荐

1. 动态切换数据源的最佳实践
2. Gateway
3. 缓存神器-JetCache
4. Mybatis 缓存机制
5. 为什么 MySQL 单表数据量最好别超过 2000w
6. IoC 思想简单而深邃
7. ThreadLocal