MapStruct 用法
一、MapStruct 简介
mapstruct是一种实体类映射框架,能够通过Java注解将一个实体类的属性安全地赋值给另一个实体类。有了mapstruct,只需要定义一个映射器接口,声明需要映射的方法,在编译过程中,mapstruct会自动生成该接口的实现类,实现将源对象映射到目标对象的效果。
二、MapStruct 使用
切记:使用过程中遇到问题一定要看下面的必坑指南
1.引入依赖
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct</artifactId>
<version>1.5.2.Final</version>
</dependency>
这个依赖项会导入MapStruct的核心注释。由于MapStruct在编译时工作,并且会集成到像Maven和Gradle这样的构建工具上,我们还必须在<build中/>标签中添加一个插件maven-compiler-plugin,并在其配置中添加annotationProcessorPaths,该插件会在构建时生成对应的代码。
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<!--以下为mapstruct所需配置-->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.5.1</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
<annotationProcessorPaths>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>1.5.2.Final</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
</build>
2. 基本映射
1.相同字段间映射
我们先从一些基本的映射开始。我们会创建一个UserInfo 对象和一个UserInfoDTO 对象,为了方便起见,它们的属性字段都使用相同的名称。
@Data
@TableName(value = "user_info")
public class UserInfo {
private String id;
private String name;
private String sex;
private String email;
}
@Data
public class UserInfoDTO {
private String id;
private String name;
private String sex;
private String email;
}
现在,为了在这两者之间进行映射,我们要创建一个UserInfoConvert接口。对该接口使用@Mapper注解,MapStruct就会知道这是两个类之间的映射器。
@Mapper
public interface UserInfoConvert {
UserInfoConvert INSTANCE = Mappers.getMapper(UserInfoConvert.class);
UserInfoDTO toDTO(UserInfo userInfo);
}
这段代码中创建了一个UserInfoConvert类型的实例INSTANCE,在生成对应的实现代码后,这就是我们调用的“入口”。
我们在接口中定义了toDTO()方法,该方法接收一个UserInfo实例为参数,并返回一个UserInfoDTO实例。这足以让MapStruct知道我们想把一个UserInfo
实例映射到一个UserInfoDTO实例。当我们构建/编译应用程序时,MapStruct注解处理器插件会识别UserInfoConvert接口并为其生成一个实现类。
@Generated(
value = "org.mapstruct.ap.MappingProcessor",
date = "2022-07-19T14:15:05+0800",
comments = "version: 1.5.2.Final, compiler: javac, environment: Java 1.8.0_181 (Oracle Corporation)"
)
public class UserInfoConvertImpl implements UserInfoConvert {
@Override
public UserInfoDTO toDTO(UserInfo userInfo) {
if ( userInfo == null ) {
return null;
}
UserInfoDTO userInfoDTO = new UserInfoDTO();
return userInfoDTO;
}
}
UserInfoConvertImpl 类中包含一个toDTO()方法,将我们的UserInfo 属性值映射到userInfoDTO
的属性字段中。如果要将UserInfo 实例映射到一个userInfoDTO 实例,可以这样写:
UserInfoDTO userInfoDTO = UserInfoConvert.INSTANCE.toDTO(userInfo);
2.不同字段间映射
通常,模型和DTO的字段名不会完全相同。由于团队成员各自指定命名,以及针对不同的调用服务,开发者对返回信息的打包方式选择不同,名称可能会有轻微的变化。
注意下面两个实体中的email字段不一致
public class UserInfo {
private String id;
private String name;
private String sex;
private String email;
}
@Data
public class UserInfoDTO {
private String id;
private String name;
private String sex;
private String myEmail;
}
现在,我们需要让 UserMapper 知道这里的不一致。我们可以使用 @Mapping 注解,并设置其内部的 source 和 target 标记分别指向不一致的两个字段。
@Mapper
public interface UserInfoConvert {
UserInfoConvert INSTANCE = Mappers.getMapper(UserInfoConvert.class);
@Mapping(target = "myEmail", source = "email")
UserInfoDTO toDTO(UserInfo userInfo);
}
生成的实现类
@Generated(
value = "org.mapstruct.ap.MappingProcessor",
date = "2022-07-19T15:22:09+0800",
comments = "version: 1.5.2.Final, compiler: javac, environment: Java 1.8.0_181 (Oracle Corporation)"
)
public class UserInfoConvertImpl implements UserInfoConvert {
@Override
public UserInfoDTO toDTO(UserInfo userInfo) {
if ( userInfo == null ) {
return null;
}
UserInfoDTO userInfoDTO = new UserInfoDTO();
// 注意这里,已经自动转换了
userInfoDTO.setMyEmail( userInfo.getEmail() );
userInfoDTO.setId( userInfo.getId() );
userInfoDTO.setName( userInfo.getName() );
userInfoDTO.setSex( userInfo.getSex() );
return userInfoDTO;
}
}
三、避坑指南
1号坑
Error:(20, 5) java: No property named "***" exists in source parameter(s). Type "***" has no properties.
原因: annotationProcessorPaths中缺少lombok插件
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.5.1</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
<annotationProcessorPaths>
<!--缺少lombok-->
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>1.5.2.Final</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
</build>
解决办法:annotationProcessorPaths中加上lombok插件
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.5.1</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
<annotationProcessorPaths>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.20</version>
</path>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>1.5.2.Final</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
2号坑
Error:(20, 5) java: No property named "***" exists in source parameter(s). Type "***" has no properties.
如果annotationProcessorPaths有lombok和mapstruct-processor,查看lombok是否放在mapstruct-processor后面,切记lombok要放在mapstruct-processor之前。
错误方式:
<annotationProcessorPaths>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>1.5.2.Final</version>
</path>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.20</version>
</path>
</annotationProcessorPaths>
正确方式:
<annotationProcessorPaths>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>1.18.20</version>
</path>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>1.5.2.Final</version>
</path>
</annotationProcessorPaths>
未完待续-------
MapStruct官方文档