mapstruct

MapStruct - Java bean 映射，简单的方法！

• 什么是MapStruct？
• 要求
• 使用映射结构
• 梅文
• 摇篮
• 文档和获取帮助
• 从源头构建
• 链接
• 许可

什么是MapStruct？

MapStruct 是一个 Java 注释处理器，旨在为 Java bean 类生成类型安全的高性能映射器，包括对 Java 16+ 记录的支持。通过自动创建映射，MapStruct 消除了繁琐且容易出错的手动编码的需要。生成器提供合理的默认值和内置类型转换，使其能够轻松处理标准映射，同时还为自定义配置或专门的映射行为提供灵活性。通过无缝集成到现代 Java 项目中，MapStruct 可以在传统 bean、记录甚至复杂的层次结构之间进行映射，使其成为适用于各种 Java 应用程序的适应性工具。

与运行时工作的映射框架相比，MapStruct 具有以下优点：

• 通过使用普通方法调用而不是反射来快速执行
• 编译时类型安全。只能映射相互映射的对象和属性，因此不会意外地将订单实体映射到客户 DTO 等。
• 自包含代码——无运行时依赖
• 如果出现以下情况，请在构建时清除错误报告：
  • 映射不完整（并非所有目标属性都已映射）
  • 映射不正确（找不到正确的映射方法或类型转换）
• 易于调试的映射代码（或可手动编辑 - 例如，如果生成器中出现错误）

要创建两种类型之间的映射，请声明一个映射器接口，如下所示：

 @ Mapper
public interface CarMapper {

    CarMapper INSTANCE = Mappers . getMapper ( CarMapper . class );

    @ Mapping ( target = "seatCount" , source = "numberOfSeats" )
    CarDto carToCarDto ( Car car );
}

在编译时MapStruct将生成该接口的实现。生成的实现使用纯Java 方法调用来映射源对象和目标对象，即不涉及反射。默认情况下，如果属性在源和目标中具有相同的名称，则属性会被映射，但您可以使用@Mapping和一些其他注释来控制这一点和许多其他方面。

要求

MapStruct 需要 Java 1.8 或更高版本。

使用映射结构

MapStruct 在命令行构建（普通 javac，通过 Maven、Gradle、Ant 等）和 IDE 中工作。

对于 Eclipse，正在开发一个专用插件（请参阅 https://github.com/mapstruct/mapstruct-eclipse）。它超越了注释处理器的功能，为注释属性、快速修复等提供内容帮助。

对于 IntelliJ，该插件可在 IntelliJ 市场中使用（请参阅 https://plugins.jetbrains.com/plugin/10036-mapstruct-support）。

梅文

对于基于 Maven 的项目，请将以下内容添加到 POM 文件中以便使用 MapStruct（依赖项可在 Maven Central 中找到）：

...
< properties >
    < org .mapstruct.version>1.6.3</ 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.13.0</ version >
            < configuration >
                < source >17</ source >
                < target >17</ target >
                < annotationProcessorPaths >
                    < path >
                        < groupId >org.mapstruct</ groupId >
                        < artifactId >mapstruct-processor</ artifactId >
                        < version >${org.mapstruct.version}</ version >
                    </ path >
                </ annotationProcessorPaths >
            </ configuration >
        </ plugin >
    </ plugins >
</ build >
...

摇篮

对于 Gradle，您需要以下内容：

plugins {
    .. .
    id " com.diffplug.eclipse.apt " version " 3.26.0 " // Only for Eclipse
}

dependencies {
    .. .
    implementation ' org.mapstruct:mapstruct:1.6.3 '

    annotationProcessor ' org.mapstruct:mapstruct-processor:1.6.3 '
    testAnnotationProcessor ' org.mapstruct:mapstruct-processor:1.6.3 ' // if you are using mapstruct in test code
}
.. .

如果您不使用依赖项管理工具，您可以从发布页面获取分发包。

文档和获取帮助

要了解有关 MapStruct 的更多信息，请参阅项目主页。参考文档详细介绍了所有提供的功能。如果您需要帮助，请在讨论中提问。

从源头构建

MapStruct 使用 Maven 进行构建。从源代码构建 MapStruct 需要 Java 11。要构建完整的项目，请运行

 ./mvnw clean install

从项目目录的根目录。要跳过分发模块，请运行

 ./mvnw clean install -DskipDistribution=true

导入IDE

MapStruct 使用 gem 注释处理器为其自己的注释生成映射 gem。因此，为了在 IDE 中无缝集成，需要启用注释处理。

智能

确保您至少拥有 IntelliJ 2018.2.x（需要，因为maven-compiler-plugin对annotationProcessors的支持来自该版本）。在 IntelliJ 中启用注释处理（构建、执行、部署 -> 编译器 -> 注释处理器）

蚀

确保您已安装 m2e_apt 插件。

链接

• 主页
• 源代码
• 下载
• 问题跟踪器
• 用户组
• CI构建

许可

MapStruct 根据 Apache 许可证 2.0 版（“许可证”）获得许可；除非遵守许可证，否则您不得使用该项目。您可以从 https://www.apache.org/licenses/LICENSE-2.0 获取许可证副本。