当前位置：首页 > news >正文

深入探究MapStruct：高效Java Bean映射工具的全方位解析

news 来源：原创 2025/4/26 0:09:00

一、引言

在Java开发中，对象之间的映射是一个常见且重要的任务。当我们从一个数据源（如数据库、网络服务等）获取数据后，往往需要将这些数据从一种数据模型转换为另一种数据模型，简单点说就是业务上老有接口抽取数据，然后插入自己的库，字段名老是不同，一个个赋值太麻烦，反正用这个省事。传统的做法是手动编写大量的getter和setter方法来完成属性的赋值，这种方式不仅繁琐、容易出错，而且代码的可维护性较差。为了解决这些问题，出现了许多对象映射工具，其中MapStruct就是一款备受青睐的高效映射工具。

二、MapStruct简介

2.1 什么是MapStruct

MapStruct是一个基于Java注解的代码生成器，它可以在编译时自动生成类型安全的Bean映射代码。与其他运行时的映射工具（如Dozer、ModelMapper等）不同，MapStruct在编译阶段就生成了映射代码，因此具有更高的性能。它的主要目标是简化Java Bean之间的映射过程，减少手动编写映射代码的工作量。

官网文章地址：https://mapstruct.org/documentation/dev/reference/html/#Preface

git地址：https://gitee.com/uzongn/mapstruct_demo

2.2 核心特点

编译时生成代码：在编译阶段生成映射代码，避免了运行时的反射开销，提高了性能。
类型安全：基于注解和编译时检查，确保映射代码的类型安全性，减少运行时错误。
易于使用：通过简单的注解配置，即可实现复杂的映射逻辑。
高度可定制：支持自定义映射方法、转换逻辑和映射策略。

三、MapStruct的使用步骤

3.1 添加依赖

在使用MapStruct之前，需要在项目中添加相应的依赖。如果你使用的是Maven项目，可以在pom.xml文件中添加以下依赖：

<dependency><groupId>org.mapstruct</groupId><artifactId>mapstruct</artifactId><version>1.5.5.Final</version>
</dependency>
<dependency><groupId>org.mapstruct</groupId><artifactId>mapstruct-processor</artifactId><version>1.5.5.Final</version><scope>provided</scope>
</dependency>

如果你使用的是Gradle项目，可以在build.gradle文件中添加以下依赖：

implementation 'org.mapstruct:mapstruct:1.5.5.Final'
annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'

3.2 定义源对象和目标对象

假设我们有一个User实体类和一个UserDto数据传输对象，用于在不同层之间传输用户信息。

// 源对象：User实体类
public class User {private Long id;private String name;private int age;private String email;// 构造函数、getter和setter方法public User() {}public User(Long id, String name, int age, String email) {this.id = id;this.name = name;this.age = age;this.email = email;}public Long getId() {return id;}public void setId(Long id) {this.id = id;}public String getName() {return name;}public void setName(String name) {this.name = name;}public int getAge() {return age;}public void setAge(int age) {this.age = age;}public String getEmail() {return email;}public void setEmail(String email) {this.email = email;}
}// 目标对象：UserDto数据传输对象
public class UserDto {private Long id;private String fullName;private int userAge;private String userEmail;// 构造函数、getter和setter方法public UserDto() {}public UserDto(Long id, String fullName, int userAge, String userEmail) {this.id = id;this.fullName = fullName;this.userAge = userAge;this.userEmail = userEmail;}public Long getId() {return id;}public void setId(Long id) {this.id = id;}public String getFullName() {return fullName;}public void setFullName(String fullName) {this.fullName = fullName;}public int getUserAge() {return userAge;}public void setUserAge(int userAge) {this.userAge = userAge;}public String getUserEmail() {return userEmail;}public void setUserEmail(String userEmail) {this.userEmail = userEmail;}
}

3.3 创建映射接口

使用@Mapper注解创建一个映射接口，定义源对象和目标对象之间的映射方法。

import org.mapstruct.Mapper;
import org.mapstruct.Mapping;@Mapper
public interface UserMapper {UserMapper INSTANCE = org.mapstruct.factory.Mappers.getMapper(UserMapper.class);@Mapping(source = "name", target = "fullName")@Mapping(source = "age", target = "userAge")@Mapping(source = "email", target = "userEmail")UserDto userToUserDto(User user);
}

在上述代码中，@Mapper注解表示这是一个MapStruct的映射接口。INSTANCE是一个静态常量，用于获取映射接口的实例。@Mapping注解用于指定源对象和目标对象之间的属性映射关系，source属性指定源对象的属性名，target属性指定目标对象的属性名。

3.4 使用映射接口进行对象映射

public class Main {public static void main(String[] args) {User user = new User(1L, "John Doe", 30, "johndoe@example.com");UserDto userDto = UserMapper.INSTANCE.userToUserDto(user);System.out.println("UserDto: " + userDto.getFullName() + ", " + userDto.getUserAge() + ", " + userDto.getUserEmail());}
}

在上述代码中，我们创建了一个User对象，并调用UserMapper的userToUserDto方法将其转换为UserDto对象。最后，打印出UserDto对象的属性信息。

四、常见使用场景

4.1 数据传输对象（DTO）与实体对象之间的映射

在Web开发中，为了避免将实体对象直接暴露给客户端，通常会使用数据传输对象（DTO）来封装需要传输的数据。MapStruct可以方便地将实体对象转换为DTO对象，以及将DTO对象转换为实体对象。

// 实体对象转换为DTO对象
User user = new User(1L, "John Doe", 30, "johndoe@example.com");
UserDto userDto = UserMapper.INSTANCE.userToUserDto(user);// DTO对象转换为实体对象
User newUser = UserMapper.INSTANCE.userDtoToUser(userDto);

4.2 不同数据库表之间的数据映射

在进行数据库操作时，可能会涉及到不同表之间的数据映射。例如，从一个数据库表中查询出的数据需要映射到另一个数据库表的实体对象中。MapStruct可以帮助我们快速实现这种映射。

// 假设我们有两个数据库表对应的实体类：Order和OrderDto
@Mapper
public interface OrderMapper {OrderMapper INSTANCE = org.mapstruct.factory.Mappers.getMapper(OrderMapper.class);@Mapping(source = "orderNumber", target = "orderNo")@Mapping(source = "totalAmount", target = "amount")OrderDto orderToOrderDto(Order order);
}

4.3 微服务之间的数据交互

在微服务架构中，不同的微服务可能使用不同的数据模型。当一个微服务需要调用另一个微服务的接口时，需要将自己的数据模型转换为对方的数据模型。MapStruct可以简化这种数据转换过程。

// 假设我们有两个微服务：UserService和UserManagementService
// UserService使用User实体类，UserManagementService使用UserVo视图对象
@Mapper
public interface UserServiceMapper {UserServiceMapper INSTANCE = org.mapstruct.factory.Mappers.getMapper(UserServiceMapper.class);@Mapping(source = "id", target = "userId")@Mapping(source = "name", target = "userName")UserVo userToUserVo(User user);
}

五、高级用法

5.1 自定义映射方法

有时候，源对象和目标对象之间的属性映射关系比较复杂，无法通过简单的@Mapping注解来实现。这时可以在映射接口中定义自定义的映射方法。

@Mapper
public interface CustomUserMapper {CustomUserMapper INSTANCE = org.mapstruct.factory.Mappers.getMapper(CustomUserMapper.class);@Mapping(source = "name", target = "fullName")@Mapping(source = "age", target = "userAge")@Mapping(source = "email", target = "userEmail")UserDto userToUserDto(User user);default String formatEmail(String email) {return "Email: " + email;}
}

在上述代码中，我们定义了一个自定义的映射方法formatEmail，用于对邮箱地址进行格式化处理。在userToUserDto方法中，可以直接调用这个自定义方法。

5.2 映射集合

MapStruct支持对集合进行映射，例如将List<User>转换为List<UserDto>。

@Mapper
public interface UserListMapper {UserListMapper INSTANCE = org.mapstruct.factory.Mappers.getMapper(UserListMapper.class);@Mapping(source = "name", target = "fullName")@Mapping(source = "age", target = "userAge")@Mapping(source = "email", target = "userEmail")UserDto userToUserDto(User user);List<UserDto> usersToUserDtos(List<User> users);
}

在上述代码中，我们定义了一个usersToUserDtos方法，用于将List<User>转换为List<UserDto>。MapStruct会自动调用userToUserDto方法对集合中的每个元素进行映射。

5.3 映射嵌套对象

如果源对象和目标对象中包含嵌套对象，MapStruct也可以处理这种情况。

// 源对象：包含嵌套对象的User实体类
public class UserWithAddress {private Long id;private String name;private Address address;// 构造函数、getter和setter方法public UserWithAddress() {}public UserWithAddress(Long id, String name, Address address) {this.id = id;this.name = name;this.address = address;}public Long getId() {return id;}public void setId(Long id) {this.id = id;}public String getName() {return name;}public void setName(String name) {this.name = name;}public Address getAddress() {return address;}public void setAddress(Address address) {this.address = address;}
}// 嵌套对象：Address实体类
public class Address {private String street;private String city;private String country;// 构造函数、getter和setter方法public Address() {}public Address(String street, String city, String country) {this.street = street;this.city = city;this.country = country;}public String getStreet() {return street;}public void setStreet(String street) {this.street = street;}public String getCity() {return city;}public void setCity(String city) {this.city = city;}public String getCountry() {return country;}public void setCountry(String country) {this.country = country;}
}// 目标对象：包含嵌套对象的UserDto数据传输对象
public class UserWithAddressDto {private Long id;private String fullName;private AddressDto addressDto;// 构造函数、getter和setter方法public UserWithAddressDto() {}public UserWithAddressDto(Long id, String fullName, AddressDto addressDto) {this.id = id;this.fullName = fullName;this.addressDto = addressDto;}public Long getId() {return id;}public void setId(Long id) {this.id = id;}public String getFullName() {return fullName;}public void setFullName(String fullName) {this.fullName = fullName;}public AddressDto getAddressDto() {return addressDto;}public void setAddressDto(AddressDto addressDto) {this.addressDto = addressDto;}
}// 嵌套对象：AddressDto数据传输对象
public class AddressDto {private String streetName;private String cityName;private String countryName;// 构造函数、getter和setter方法public AddressDto() {}public AddressDto(String streetName, String cityName, String countryName) {this.streetName = streetName;this.cityName = cityName;this.countryName = countryName;}public String getStreetName() {return streetName;}public void setStreetName(String streetName) {this.streetName = streetName;}public String getCityName() {return cityName;}public void setCityName(String cityName) {this.cityName = cityName;}public String getCountryName() {return countryName;}public void setCountryName(String countryName) {this.countryName = countryName;}
}// 映射接口
@Mapper
public interface UserWithAddressMapper {UserWithAddressMapper INSTANCE = org.mapstruct.factory.Mappers.getMapper(UserWithAddressMapper.class);@Mapping(source = "name", target = "fullName")@Mapping(source = "address.street", target = "addressDto.streetName")@Mapping(source = "address.city", target = "addressDto.cityName")@Mapping(source = "address.country", target = "addressDto.countryName")UserWithAddressDto userWithAddressToUserWithAddressDto(UserWithAddress userWithAddress);
}