序言
本文给大家介绍 MapStruct。
一、问题引入
在我们的日常开发过程中,我们经常会将 VO、DTO、PO …… 等对象相互进行映射。实现的方式可能有以下几种:
- 自己手动进行转换
- 利用诸如 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 实体类,返回 UserDTO
UserDTO userToUserDTO(User user);
}
3.3 使用
@Test
public void test() {
User user = new User(1, "zs");
// 直接调用定义好的接口方法
// User 实体类转换成 UserDTO
UserDTO 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,我们可以采用以下的方式:
定义一个组合注解
@Retention(RetentionPolicy.CLASS) @Mapping(target = "username", source = "name") public @interface Composition { }
使用组合注解
@Mapper public interface UserMapper { UserMapper INSTANCE = Mappers.getMapper(UserMapper.class); @Composition UserDTO 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;
}
@Override
public 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 {
// 装饰器中采用注解获取
@Resource
private UserMapper delegate;
@Override
public 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
- MapStruct 依赖与 Lombok 依赖可能存在冲突的情况,在引入 MapStruct 相关依赖时要严格安装本文提供的顺序引入。
- MapStruct 的原理是通过定义的接口,自动帮助开发人员生成映射代码。所以当修改了接口中内容,若没有立即生效则可能需要使用
mvn clean
或mvn compile
等命令清理一下自动生成的旧版本代码。