MapStruct详解与使用指南
1. 简介
MapStruct 是一个基于注解的 Java Bean 映射框架，专门用于简化对象之间的转换（即 DTO 与 Entity 之间的转换）。与其他一些常见的映射工具（如 Dozer 或 ModelMapper）不同，MapStruct 在编译时生成代码，性能极高，并且可以在编译时捕获大部分错误，避免运行时异常。
1.1 为什么使用 MapStruct？
对象映射是 Java 开发中的常见需求，例如将数据库实体（Entity）映射到数据传输对象（DTO）中。然而，手动写映射代码可能导致冗长且重复的代码，难以维护和调试。MapStruct 通过自动生成映射代码，减少了开发者的工作量，并确保映射操作的高效与安全。
1.2 MapStruct 的优势
- 编译时生成代码：相比于运行时映射工具，MapStruct 在编译时生成映射代码，性能更高，且能捕获映射错误。
- 轻量级：不需要引入额外的依赖库，只需添加 MapStruct 注解即可。
- 灵活性：支持自定义映射逻辑，允许根据需求对映射行为进行调整。
- 类型安全：映射时发生的错误在编译期被捕获，减少了运行时出错的可能性。
2. 安装与配置
2.1 Maven 配置
使用 MapStruct 之前，需要在项目的 pom.xml 文件中引入必要的依赖。
<dependencies>
<!-- MapStruct 依赖 -->
<dependency>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct</artifactId>
<version>1.5.3.Final</version> <!-- 最新版本可查阅官方文档 -->
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<configuration>
<source>1.8</source>
<target>1.8</target>
<annotationProcessorPaths>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>1.5.3.Final</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
</plugins>
</build>
2.2 Gradle 配置
如果使用 Gradle，需在 build.gradle 文件中进行如下配置：
dependencies {
implementation 'org.mapstruct:mapstruct:1.5.3.Final'
annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.3.Final'
}
3. 基本使用
MapStruct 使用非常简单，主要通过定义一个接口或抽象类，使用 @Mapper 注解来定义映射关系。MapStruct 会在编译时为我们生成实现类。
3.1 简单的 DTO 与 Entity 映射
假设我们有一个 UserEntity 和 UserDTO，它们之间字段名称相同，下面是如何通过 MapStruct 进行映射的示例。
// DTO 类
public class UserDTO {
private Long id;
private String name;
private String email;
// Getters 和 Setters
}
// Entity 类
public class UserEntity {
private Long id;
private String name;
private String email;
// Getters 和 Setters
}
3.2 定义映射接口
import org.mapstruct.Mapper;
import org.mapstruct.factory.Mappers;
@Mapper
public interface UserMapper {
// 获取生成的实例
UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);
// 定义映射方法
UserDTO toUserDTO(UserEntity userEntity);
UserEntity toUserEntity(UserDTO userDTO);
}
在编译时，MapStruct 会为我们自动生成 UserMapperImpl 实现类，负责将 UserEntity 和 UserDTO 之间相互转换。
3.3 使用 MapStruct 进行转换
public class Main {
public static void main(String[] args) {
UserEntity userEntity = new UserEntity();
userEntity.setId(1L);
userEntity.setName("John Doe");
userEntity.setEmail("john.doe@example.com");
// 使用 MapStruct 进行转换
UserDTO userDTO = UserMapper.INSTANCE.toUserDTO(userEntity);
System.out.println("UserDTO Name: " + userDTO.getName());
// 反向转换
UserEntity convertedEntity = UserMapper.INSTANCE.toUserEntity(userDTO);
System.out.println("UserEntity Name: " + convertedEntity.getName());
}
}
通过这样简单的接口定义，MapStruct 会在编译时自动生成 UserMapperImpl，并将对象从 Entity 映射到 DTO。
4. 高级使用
4.1 字段名不同时的映射
有时，源对象与目标对象的字段名称并不一致，这种情况下，我们可以通过 @Mapping 注解来指定映射关系。
4.1.1 实例
假设 UserEntity 中的 email 字段在 UserDTO 中叫 userEmail，我们需要手动配置映射。
public class UserDTO {
private Long id;
private String name;
private String userEmail;
// Getters 和 Setters
}
@Mapper
public interface UserMapper {
@Mapping(source = "email", target = "userEmail")
UserDTO toUserDTO(UserEntity userEntity);
@Mapping(source = "userEmail", target = "email")
UserEntity toUserEntity(UserDTO userDTO);
}
通过 @Mapping 注解，我们可以指定任意源对象和目标对象字段之间的映射关系。
4.2 自定义映射方法
有时，我们可能需要对某些字段进行自定义处理，比如格式化日期或处理复杂的转换逻辑。可以通过在 Mapper 接口中定义自定义方法来实现。
4.2.1 日期格式转换示例
public class UserDTO {
private Long id;
private String name;
private String email;
private String birthDate; // 字符串格式的日期
// Getters 和 Setters
}
@Mapper
public interface UserMapper {
@Mapping(source = "birthDate", target = "birthDate", dateFormat = "yyyy-MM-dd")
UserDTO toUserDTO(UserEntity userEntity);
}
通过在 @Mapping 注解中指定 dateFormat，MapStruct 能够自动将日期转换为指定的格式。
5. 集合与嵌套映射
MapStruct 也支持集合和嵌套对象的映射。
5.1 集合映射
假设我们有一组 UserEntity 列表，需要将它们转换为 UserDTO 列表。
@Mapper
public interface UserMapper {
List<UserDTO> toUserDTOList(List<UserEntity> userEntities);
}
MapStruct 会自动处理列表中每个对象的映射。
5.2 嵌套对象映射
如果 UserEntity 中包含一个嵌套对象，比如 Address，我们也可以通过定义嵌套对象的映射来实现。
public class UserEntity {
private Long id;
private String name;
private String email;
private AddressEntity address;
// Getters 和 Setters
}
public class AddressEntity {
private String street;
private String city;
// Getters 和 Setters
}
@Mapper
public interface UserMapper {
@Mapping(source = "address.street", target = "street")
@Mapping(source = "address.city", target = "city")
UserDTO toUserDTO(UserEntity userEntity);
}
6. 总结
MapStruct 是一个非常强大的对象映射工具，它通过注解和编译时生成代码，大幅简化了 DTO 与 Entity 之间的转换过程。它不仅提供了基础的字段映射功能，还支持复杂的自定义逻辑、集合映射以及嵌套对象映射。对于需要频繁进行对象转换的项目来说，MapStruct 是一个高效、简洁且性能优越的解决方案。
评论区