MapStruct使用教程(内含代码实战)

MapStruct:简化Java对象映射的强大工具

引言

    对象之间的映射是每个 Java 开发人员在日常工作中都会遇到的任务。例如，将数据库实体映射到DTO（数据传输对象），或者将领域对象映射到视图对象。这些映射任务通常涉及大量重复的代码，增加了开发的复杂性。MapStruct 是一个强大的 Java 映射框架，它可以显著简化对象之间的映射工作，提高代码的可维护性和可读性。最近在开发中恰巧使用到了这个框架，用起来比较顺手，我们就来一起研究研究

MapStruct 的原理

    在了解 MapStruct 的基本用法之前，让我们先理解它的工作原理。MapStruct 是一个基于注解的编译时代码生成工具，它通过生成映射代码来消除手动编写映射方法的需求。以下是 MapStruct 的基本原理：

1. 映射接口定义：首先，您需要定义一个 Java 接口，其中包含映射方法的声明。这个接口用 @Mapper 注解进行标记，以通知 MapStruct 进行代码生成。
2. 代码生成：在编译时，MapStruct 的注解处理器会解析您的映射接口，并生成映射代码。这些生成的代码将根据接口中的映射方法来执行对象之间的映射。
3. 映射方法：生成的映射方法将遵循您在接口中定义的规则，并使用相应的映射策略执行对象之间的映射。
4. 集成到项目：生成的代码将与您的项目一起编译，并可以直接使用。

基本用法

    接下来，我们将介绍 MapStruct 的基本用法。我们将从配置和简单映射开始，然后逐步介绍更高级的映射场景。

配置 Maven 依赖

    要使用 MapStruct，首先在您的项目中添加 MapStruct 的 Maven 依赖。在 pom.xml 文件中，添加以下依赖：

<dependency>
   <groupId>org.mapstruct</groupId>
  <artifactId>mapstruct</artifactId>
  <version>1.4.2.Final</version>
</dependency>

创建映射接口

    接下来，创建一个映射接口，该接口将包含映射方法的声明。例如，假设我们有一个 User 类和一个 UserDTO 类，我们想要在它们之间进行映射：

@Mapper
public interface UserMapper {
   UserDTO userToUserDTO(User user);
   User userDTOToUser(UserDTO userDTO);
}

在上面的代码中，我们用 @Mapper 注解标记了接口，告诉 MapStruct 生成映射代码。然后，我们定义了两个方法，一个用于将 User 对象映射到 UserDTO 对象，另一个用于将 UserDTO 对象映射回 User 对象。

生成映射代码

    配置好 MapStruct 的依赖和插件后，使用 Maven 构建项目。MapStruct 将在编译时生成映射代码，并将其放在 target/generated-sources/annotations 目录下。
现在，可以使用生成的映射接口来执行对象之间的映射。以下是一个简单的示例：

User user = new User("John", "Doe");
UserDTO userDTO = UserMapper.INSTANCE.userToUserDTO(user);

如上所示，可以使用 UserMapper.INSTANCE 来调用映射方法，将 User 对象映射到 UserDTO 对象。

高级用法

自定义映射

    有时候，可能需要自定义映射行为，例如处理特定字段的转换或执行复杂逻辑。MapStruct 允许使用 @Mapping 注解来自定义映射。以下是一个示例：

@Mapper
public interface UserMapper {
  @Mapping(target = "email", source = "userEmailAddress")
  UserDTO userToUserDTO(User user);
}

在上面的示例中，我们使用 @Mapping 注解来指定目标属性和源属性之间的映射关系。这允许在不同属性名的情况下进行映射。

集合映射

    MapStruct 也可以处理集合映射。假设需要将用户列表映射为用户DTO列表，可以定义如下映射方法：

@Mapper
public interface UserMapper {
   List<UserDTO> usersToUserDTOs(List<User> users);
}

MapStruct 将会为我们自动生成代码，将用户列表映射为用户DTO列表。

实战示例

    接下来，我们将通过一个实际示例来演示 MapStruct 在 Spring Boot 项目中的使用。假设我们正在构建一个用户注册 API，需要将用户数据从DTO映射到领域对象，以及处理异常情况。

步骤 1：创建 Spring Boot 项目

    首先，创建一个 Spring Boot 项目。我们可以使用 Spring Initializer 或手动创建项目。

步骤 2：添加依赖

    在项目的 pom.xml 文件中，添加 MapStruct 依赖和插件，以及 Spring Boot 相关依赖。

步骤 3：创建领域对象和 DTO

    创建一个领域对象 User 和一个 DTO UserDTO，它们之间需要进行映射。

步骤 4：创建 MapStruct 映射接口

    创建一个 MapStruct 映射接口 UserMapper，定义映射方法。

步骤 5：生成映射代码

    使用 Maven 构建项目，MapStruct 将在编译时生成映射代码。

步骤 6：Spring Boot 服务

    创建一个 Spring Boot 服务，处理用户注册的请求。在控制器中，使用 MapStruct 进行对象之间的映射。

@RestController
@RequestMapping("/users")
public class UserController {
   private final UserService userService;
   private final UserMapper userMapper;

   @Autowired
   public UserController(UserService userService, UserMapper userMapper) {
       this.userService = userService;
       this.userMapper = userMapper;
   }

   @PostMapping("/register")
  public ResponseEntity<UserDTO> registerUser(@RequestBody UserDTO userDTO) {
       User user = userMapper.userDTOToUser(userDTO);
       User registeredUser = userService.registerUser(user);
       UserDTO registeredUserDTO = userMapper.userToUserDTO(registeredUser);
       return new ResponseEntity<>(registeredUserDTO, HttpStatus.CREATED);
   }
}

在上面的示例中，我们使用 UserMapper 进行用户DTO到领域对象的映射。

步骤 7：异常处理

    在服务层或控制器层处理异常，然后将异常信息映射到相应的错误响应。这可以通过全局异常处理器来实现。

@ControllerAdvice
public class ExceptionHandlerController {

  @ExceptionHandler(UserNotFoundException.class)
   public ResponseEntity<ErrorResponse> handleUserNotFound(UserNotFoundException ex) {
       ErrorResponse errorResponse = new ErrorResponse("User not found", ex.getMessage());
       return new ResponseEntity<>(errorResponse, HttpStatus.NOT_FOUND);
   }

   @ExceptionHandler(UserRegistrationException.class)
   public ResponseEntity<ErrorResponse> handleUserRegistrationError(UserRegistrationException ex) {
       ErrorResponse errorResponse = new ErrorResponse("User registration failed", ex.getMessage());
       return new ResponseEntity<>(errorResponse, HttpStatus.BAD_REQUEST);
   }
}

这允许将异常信息映射到适当的 HTTP 响应。

步骤 8：测试

    编写单元测试和集成测试，确保映射和异常处理的正确性。
这就是使用 MapStruct 在 Spring Boot 项目中进行对象映射的示例。这个工具使开发更加高效，同时也提高了代码质量。

性能考虑

    MapStruct 以其编译时生成的特性而闻名，这为它提供了显著的性能优势。与运行时生成映射代码的工具相比，MapStruct 生成的代码更加高效，因为它不需要在运行时执行反射或复杂的映射逻辑。这意味着在映射大量对象时，MapStruct 提供了更好的性能。为了进一步提高性能，我们可以考虑以下几个方面：

• 使用 MapStruct 的 @MapperConfig 注解来配置映射策略，以减少生成的代码的复杂性。
• 使用 MapStruct 的 @Mapping 注解来明确指定属性的映射关系，以避免不必要的转换。
• 优化我们的数据模型，以减少不必要的属性或嵌套对象。

综合考虑这些因素，MapStruct 提供了出色的性能，特别适合在性能敏感的应用程序中使用。

与其他映射工具的比较

    MapStruct 不是唯一的 Java 对象映射工具，还有其他工具如 Dozer 和 ModelMapper。以下是 MapStruct 与其他映射工具的比较：

• MapStruct vs. Dozer:

1. Dozer 是一个运行时映射框架，它提供了更多的灵活性，但性能通常较差。相比之下，MapStruct 在编译时生成映射代码，性能更高，但可能不如 Dozer 灵活。
2. 如果更注重性能，或者需要在编译时检测映射问题，那么 MapStruct 是更好的选择。

• MapStruct vs. ModelMapper:

1. ModelMapper 与 MapStruct 类似，它也是编译时生成映射代码的工具。性能相对较高，但在某些复杂映射情况下可能需要更多的配置。
2. 选择 MapStruct 还是 ModelMapper 取决于您的项目需求，MapStruct 通常被认为更易于使用和配置。

总结

MapStruct是一个Java注解处理器库，用于生成对象之间的映射代码。它的主要目的是简化对象之间的转换，特别是在DTO（Data Transfer Object）和领域对象之间进行映射的情况下非常有用。以下是有关MapStruct的一些关键要点：

1. 简化对象映射：MapStruct允许您通过定义接口和注解的方式，生成对象之间的映射代码，从而减少手动编写重复性的映射代码的工作。
2. 注解处理器：MapStruct是一个基于注解处理器的库，它在编译时生成映射代码，因此不会对运行时性能造成额外的负担。
3. 类型安全：MapStruct在编译时执行类型检查，因此您不必担心在运行时遇到类型错误。
4. 支持多种映射策略：MapStruct支持多种映射策略，包括默认映射、自定义映射方法、构造函数映射和更复杂的映射逻辑。
5. 可配置性：您可以通过注解和配置选项来自定义生成的映射代码，以满足特定需求。
6. 集成性：MapStruct能够与多个常见的Java框架和库（如Spring、Hibernate、JPA等）协同工作，使对象映射更容易集成到您的应用程序中。
7. 生成的代码：MapStruct生成的代码通常包括在Mapper接口中，这些接口包含了从源对象到目标对象的映射方法。您可以使用这些方法在应用程序中执行对象之间的映射。
8. IDE支持：大多数主流的Java集成开发环境（IDE）都提供对MapStruct的支持，使其易于使用和调试。

点赞收藏，富婆包养✋✋