使用MapStruct实现Java对象映射的示例代码_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
性能	极高	较低 (运行时反射)	极高 (编译时生成)
类型安全	编译时	运行时 (可能沉默失败)	编译时 (推荐)
代码简洁度	差	好	极好
可维护性	差	中	极好