在分层架构的开发中，经常遇到以下场景：将 DAO 查询出的 Entity 对象，转换为返回给前端的 VO 对象；或者将前端传来的 DTO 对象，转换为要存入数据库的 Entity 对象。

每当两个对象的字段很多时，用get和set的方法完成“数据搬运”的过程就比较麻烦，接下来介绍一下使用MapStruct的方法。

一、什么是 MapStruct？

MapStruct 是一个 Java 注解处理器，用于在编译时自动生成类型安全、高性能的对象映射代码。 请注意这里的几个关键词：

编译时生成代码：它不是像 `BeanUtils.copyProperties` 那样在运行时使用反射，所以性能极高，与你手写的 `get/set` 代码完全一样。

类型安全：它在编译期间就会对字段类型进行检查。如果源对象和目标对象的字段类型不兼容，编译会直接报错，让你能尽早发现问题。

注解驱动：你只需要定义一个简单的 Java 接口并添加注解，MapStruct 就会在幕后为你完成所有繁重的工作。

二、实战演练：三步集成 MapStruct

让我们通过一个将 `DataProductItemDto` (DTO) 转换为 `DataProduct` (Entity) 的实例，来看看 MapStruct 的使用方法。

第一步：添加 Maven 依赖 (`pom.xml`)

这是整个集成的基础。需要告诉 Maven 项目要使用 MapStruct，并配置好编译器。

```xml
<!-- 1. 在 <properties> 中统一定义版本号 -->
<properties>
    <org.mapstruct.version>1.5.5.Final</org.mapstruct.version>
    <lombok.version>1.18.30</lombok.version>
    <lombok-mapstruct-binding.version>0.2.0</lombok-mapstruct-binding.version>
</properties>

<!-- 2. 在 <dependencies> 中添加核心库 -->
<dependencies>
    <!-- MapStruct 核心库 -->
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>${org.mapstruct.version}</version>
    </dependency>

    <!-- (如果使用Lombok) 这是让 MapStruct 和 Lombok 和谐共处的关键 -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok-mapstruct-binding</artifactId>
        <version>${lombok-mapstruct-binding.version}</version>
    </dependency>
</dependencies>

<!-- 3. 在 <build><plugins> 中配置注解处理器 (最关键的部分) -->
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>1.8</source> <!-- 或你的 Java 版本 -->
                <target>1.8</target> <!-- 或你的 Java 版本 -->
                <annotationProcessorPaths>
                    <!-- 必须确保 Lombok 在 MapStruct 之前执行 -->
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${lombok.version}</version>
                    </path>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${org.mapstruct.version}</version>
                    </path>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok-mapstruct-binding</artifactId>
                        <version>${lombok-mapstruct-binding.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

配置要点：annotationProcessorPaths 里的顺序非常重要，确保了 Lombok 先为你的类生成 getter/setter，然后 MapStruct 才能找到并使用它们。

修改完 pom.xml 后，务必重新构建你的 Maven 项目

第二步：创建 Mapper 接口 

现在需要定义“翻译规则”。你只需要创建一个接口，剩下的交给 MapStruct。

package com.cmgii.trust.third.dtcp.converter;// 建议放在专门的 converter 包下

import com.cmgii.trust.third.dtcp.domain.DataProduct;
import com.cmgii.trust.third.dtcp.domain.vo.respVO.DataProductItemDto;
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.factory.Mappers;

import java.util.List;

@Mapper
public interface DataProductConverter {

    //提供一个全局唯一的翻译官实例
    DataProductConverter INSTANCE = Mappers.getMapper(DataProductConverter.class);

    /**
     * 将单个 DTO 转换为实体。
     * MapStruct 会自动映射所有同名、同类型的字段。
     * 我们只需为有特殊转换需求的字段（如日期格式）添加规则。
     * @param dto 源 DTO 对象
     * @return 转换后的实体对象
     */
    @Mapping(source = "listTime", target = "listTime", dateFormat = "yyyy-MM-dd'T'HH:mm:ss")
    DataProduct toDataProduct(DataProductItemDto dto);

    /**
     * 将 DTO 列表转换为实体列表。
     * MapStruct 会自动复用上面的 toEntity 方法来处理列表中的每一个元素。
     *
     * @param dtoList 源 DTO 列表
     * @return 转换后的实体列表
     */
    List<DataProduct> toDataProductList(List<DataProductItemDto> dtoList);
} 

1. @Mapper 注解

• 作用：这是 MapStruct 的核心注解。它告诉 MapStruct 的代码生成器：“嘿，这个接口不是一个普通的接口，它是一份映射规则的蓝图。请在编译时，为我自动生成一个实现了这个接口的 ...Impl 类。”

2. DataProductConverter INSTANCE = ... (单例模式)

• 作用：这是获取 Mapper 实例的经典方式（当不使用 Spring 注入时）。

• Mappers.getMapper(...): 这是 MapStruct 提供的一个工厂方法，它会找到并返回 MapStruct 在编译时为您自动生成的那个 DataProductConverterImpl 类的单例实例。

• 用法：在应用的任何地方，都可以通过 DataProductConverter.INSTANCE 来获取到这个唯一的、线程安全的“翻译官”，然后调用他的翻译方法。

3. toDataProduct(DataProductItemDto dto) - 单个对象映射

• 作用：定义了如何将一个 DataProductItemDto 对象，转换成一个 DataProduct 对象。

• MapStruct 的智能自动化：DataProductItemDto 和 DataProduct 这两个类有大量同名、同类型的字段。MapStruct 会自动识别并映射这些字段，无需为它们编写任何 @Mapping 注解。

• @Mapping(...) - 特殊规则定制:

  • source = "listTime", target = "listTime": source 指源对象（DTO）的属性，target 指目标对象（Domain）的属性。这里两者同名。

  • dateFormat = "yyyy-MM-dd'T'HH:mm:ss": 这是最关键的定制规则。它告诉 MapStruct：“当你在转换 listTime 这个字段时，请注意，源对象里的 listTime 是一个字符串，而目标对象里的是一个 Date。请你使用 "yyyy-MM-dd'T'HH:mm:ss" 这个格式，将字符串解析成 Date 对象。”

  • 这完美地解决了日期格式解析问题，而且是以一种非常声明式、非常优雅的方式。

4. toDataProductList(List<DataProductItemDto> dtoList) - 集合映射

• 作用：定义了如何将一个 DataProductItemDto 的列表，转换成一个 DataProduct 的列表。

• MapStruct 的进一步智能：MapStruct 足够智能，当它看到这个方法时，它会发现：“哦，我知道如何转换单个 DataProductItemDto（通过 toDataProduct 方法），那转换一个列表，我只需要对列表里的每个元素都调用一次 toDataProduct 方法就行了。”

• 因此，不需要为这个方法编写任何额外的 @Mapping 注解。MapStruct 会自动生成一个循环遍历并逐个转换的实现。

第三步：在 Service 中使用 Mapper

可以在业务逻辑中，用一行代码替代原来繁琐的转换过程。

@Override
    @Transactional
    public void syncDataProducts() {
        // 1. 从第三方获取所有数据产品
        List<DataProductItemDto> remoteProductsDto = cmccDtcpThirdService.selectAllDataProductList();

        // 2. 将DTO转换为实体
        List<DataProduct> dataProducts = DataProductConverter.INSTANCE.toDataProductList(remoteProductsDto);

        // 3. 批量存入数据库
        if (dataProducts != null && !dataProducts.isEmpty()) {
            dataProductMapper.batchInsertOrUpdate(dataProducts);
        }
    }

三、总结：为什么选择 MapStruct？