首页 > 软件编程 > java > MapStruct 实现 Java 对象映射

使用MapStruct实现Java对象映射的示例代码

2025-09-25 11:06:49 作者：1candobetter

本文主要介绍了使用MapStruct实现Java对象映射的示例代码,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧

在分层架构的开发中，经常遇到以下场景：将 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，并配置好编译器。

<!-- 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？

特性	手动 get/set	BeanUtils.copyProperties	MapStruct
性能	极高	较低 (运行时反射)	极高 (编译时生成)
类型安全	编译时	运行时 (可能沉默失败)	编译时 (推荐)
代码简洁度	差	好	极好
可维护性	差	中	极好

到此这篇关于使用MapStruct实现Java对象映射的文章就介绍到这了,更多相关MapStruct 实现 Java 对象映射内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！