MapStruct-比BeanUtils好一万倍的类型转换工具

1. MapStruct 简介

MapStruct 是一款基于 Java 注解处理器 的高性能对象映射工具，能在编译时自动生成类型安全的映射代码。它通过生成 getter/setter 调用来实现对象属性赋值，避免了反射带来的性能损耗，特别适用于 DTO、VO、DO 等模型间的转换场景。

---

2. 核心优势

• 高性能：编译时生成代码，运行时无反射调用，性能接近手写 getter/setter。
• 类型安全：编译时检查字段映射错误，避免运行时异常。
• 灵活性：支持复杂映射规则（如自定义格式转换、多对象合并、嵌套映射等）。
• 无依赖：生成的代码不依赖 MapStruct 库，适合生产环境。
• 易维护性：集中式映射接口，代码结构清晰，易于扩展。

---

3. 安装与配置

Maven 依赖

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
    <modelVersion>4.0.0</modelVersion>

    <properties>
        <org.mapstruct.version>1.5.5.Final</org.mapstruct.version>
    </properties>

    <!-- 请忽略这些跟标签,只需要关注下面的内容 -->
    <dependencies>
        <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct</artifactId>
            <version>${org.mapstruct.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>org.mapstruct</groupId>
                            <artifactId>mapstruct-processor</artifactId>
                            <version>${org.mapstruct.version}</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

注：需与 Lombok 配合时，需添加 lombok-mapstruct-binding 依赖。

---

4. 基础使用

定义映射接口

@Mapper  
public interface UserMapper {  
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);  

    // 基本字段映射（同名自动映射）  
    UserDTO toDTO(UserEntity user);  

    // 不同名字段映射  
    @Mapping(source = "birthYear", target = "age")  
    @Mapping(target = "address", defaultValue = "Unknown")  
    UserDTO toCustomDTO(UserEntity user);  
}

使用映射方法

UserEntity user = new UserEntity("Alice", 1990);  
UserDTO dto = UserMapper.INSTANCE.toCustomDTO(user);  
// 输出：UserDTO(name="Alice", age=35, address="Unknown")

---

5. 进阶功能

复杂映射场景

1. 多参数源映射
   合并多个源对象的字段到目标对象：

   @Mapping(source = "user.name", target = "name")  
   @Mapping(source = "address.city", target = "city")  
   UserInfoDTO merge(User user, Address address);

2. 嵌套对象映射
   自动递归映射嵌套对象：

   @Mapper  
   public interface OrderMapper {  
       @Mapping(target = "customer.name", source = "customerName")  
       OrderDTO toDTO(OrderEntity order);  
   }

3. 自定义类型转换
   支持日期、枚举等复杂类型转换：

   @Mapping(target = "createTime", source = "createTime", dateFormat = "yyyy-MM-dd")  
   @Mapping(target = "status", source = "statusCode")  
   UserDTO toDTO(UserEntity user);

4. 条件映射
   仅当条件满足时映射字段：

   @Mapping(target = "discount", conditionExpression = "java(user.isVIP())")  
   UserDTO toDTO(UserEntity user);

5. 集合映射
   自动映射 List、Set 等集合类型：

   List<UserDTO> toDTOList(List<UserEntity> users);

---

6. 注意事项

1. 字段名匹配：默认按同名映射，需显式配置不同名字段。
2. Lombok 兼容性：需添加 lombok-mapstruct-binding 依赖以避免编译冲突。
3. 编译触发：IDE 需启用注解处理器（如 IntelliJ 中勾选 Enable annotation processing）。
4. 性能调优：避免在循环中频繁创建 Mapper 实例，推荐单例模式。

---

通过 MapStruct，开发者能以声明式的方式高效处理对象映射，兼顾性能与代码可维护性。建议结合具体项目需求，逐步探索其高级特性（如逆向映射、SPI 扩展等）。