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 取得授權副本。