修復 Spring 應用程式中 MapStruct @Mapper 註解導致的 Bean 創建問題
1. 引言
建立 Bean 是 Spring 初始化應用程式元件的核心步驟之一。然而，當使用 MapStruct 的@Mapper註解時，我們可能會在應用程式啟動期間遇到意料之外的 Bean 創建錯誤。這些問題通常是由於 Spring 未能正確檢測、實例化或配置 MapStruct 產生的 Mapper 實作而導致的。因此，應用程式可能無法啟動，或會拋出各種運行時異常，表示有缺失或配置不正確的 Mapper Bean。
本教學將探討如何有效解決 Spring 應用程式中 MapStruct 的@Mapper註解導致的 bean 建立問題。我們將重點介紹如何配置 Mapper，使 Spring 能夠正確檢測、實例化和連接它們，從而確保應用程式順利啟動。此外，我們還將提供一些實用的解決方案和最佳實踐，展示如何避免常見的運行時異常、提高程式碼可維護性，並充分利用 MapStruct 的編譯時映射功能。
2. MapStruct 如何與 Spring Beans 交互
在解決這些問題之前，必須先了解 MapStruct 的運作方式以及 Spring 有時無法識別其產生的映射器的原因。
2.1. MapStruct 如何產生映射器
MapStruct 充當編譯時註解處理器，將映射介面轉換為具體實作。
為了說明這一點，考慮一個簡單的領域，它由一個Person實體及其對應的PersonDto類別組成：
public class Person {
private String name;
private int age;
// Constructors, getters, and setters
}
public class PersonDto {
private String name;
private int age;
// Constructors, getters, and setters
}映射器介面定義了這兩種類型之間的轉換：
@Mapper
public interface PersonMapper {
PersonDto toDto(Person person);
}在編譯過程中，MapStruct 會在產生的原始碼目錄中建立一個名為PersonMapperImpl的類別。這個產生的類別包含了將Person實體轉換為PersonDto物件所需的實際欄位映射邏輯。然而，儘管該類存在於生成的源代碼中，但它仍然是一個普通的Java類，沒有任何 Spring 特有的註解。因此，Spring 不會將該映射器包含在其應用程式上下文中，也不會管理其生命週期。
2.2. 為什麼 Bean 創作會失敗
Spring依賴注入機制要求所有必需的bean都已在應用程式上下文中註冊。
讓我們考慮一個聲明依賴映射器的服務：
@Autowired
private PersonMapper personMapper;當 Spring 嘗試注入此依賴項時，會觸發NoSuchBeanDefinitionException異常。這是因為MapStruct 預設不會將產生的映射器實作註冊為 Spring bean 。由於產生的PersonMapperImpl缺少 Spring 特有的註解，Spring 容器在元件掃描期間無法偵測到它。
這會造成以下幾個後果：
- Spring 找不到映射器實作。
- 依賴注入失敗。
- 應用程式啟動可能會因缺少 bean 錯誤而失敗。
這項挑戰凸顯了將產生的 MapStruct 程式碼與 Spring bean 的生命週期保持一致的必要性。
3. 為 Spring 設定 MapStruct 映射器
若要修復上一節中討論的 bean 建立錯誤，必須配置 MapStruct 以產生 Spring 可識別為託管 bean 的 mapper 實作。
3.1 啟用 Spring 元件模型
MapStruct 透過在@Mapper註解中指定componentModel = “spring”來產生–管理的 mapper bean：
@Mapper(componentModel = "spring")
public interface PersonMapper {
PersonDto toDto(Person person);
}透過這種配置，MapStruct 可以產生我們需要的實作：
@Component
public class PersonMapperImpl implements PersonMapper { ... }在這種情況下， @Component註解會註冊產生的映射器，以便 Spring 將其視為託管 bean 。因此，它成為應用程式上下文的一部分，可以注入到依賴服務或控制器中。此配置將 MapStruct 的編譯時實作與 Spring 執行時間依賴管理連接起來，消除了 bean 缺失錯誤，並確保了整個應用程式中映射器的一致性可用性。
3.2 確保已啟用標註處理
即使組件模型正確，如果沒有註解處理，MapStruct 也無法產生映射器實作。註解處理器在編譯期間執行，以產生所需的類別。如果沒有此配置，介面可以成功編譯，但實作不存在，導致 Spring 無法註冊 bean。
使用 Maven 的專案通常依賴maven-compiler-plugin來執行 MapStruct 註解處理器：
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.10.1</version>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
<version>${mapstruct.version}</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>此配置可確保 MapStruct 在編譯階段產生所有映射器實作。
對於基於 Gradle 的項目，註解處理依賴另一種設定（取決於版本）：
dependencies {
annotationProcessor 'org.mapstruct:mapstruct-processor:${mapstruct.version}'
}
新增此相依性後，Gradle 可以在編譯期間執行 MapStruct 程式碼產生器，產生 Spring 可以偵測並註冊為託管 bean 的映射器實作。
4. 普通豆類生產問題及其解決方案
即使配置了 MapStruct 並啟用了註解處理， Spring 應用程式中仍可能存在某些 bean 創建問題。以下小節概述了最常見的原因及其相應的解決方案。
4.1. Spring 未掃描包裹
Spring Boot 會自動掃描主應用程式類別所在的套件下的所有套件。如果映射器位於此路徑之外，Spring 將無法偵測到它們，從而在嘗試注入映射器時拋出NoSuchBeanDefinitionException異常。
為了解決這個問題，我們可以確保所有映射器介面都位於 Spring 掃描的套件中，或明確定義要掃描的套件：
@SpringBootApplication(scanBasePackages = "com.example")這樣，我們就可以讓 Spring 正確偵測 MapStruct 映射器並將其註冊為 bean。
4.2. Lombok和 MapStruct 之間的衝突
結合使用Lombok和 MapStruct 的專案經常會遇到一些難以察覺的編譯問題，導致 bean 創建失敗。由於Lombok和 MapStruct 都依賴註解處理器，任何衝突或錯誤的處理器順序都可能導致不同的問題：
- 不完整的模型類
- 缺少 getter 或 setter
- 錯誤的映射行為
因此，讓我們將Lombok註解處理器配置為在MapStruct之前執行：
<annotationProcessorPaths>
<path>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</path>
<path>
<groupId>org.mapstruct</groupId>
<artifactId>mapstruct-processor</artifactId>
</path>
</annotationProcessorPaths>使用 Maven 時，此調整應確保在 MapStruct 建立映射器實作之前所有模型類別都已完全生成，從而消除 Spring 應用程式中常見的 bean 注入問題。
4.3. IDE 註解處理問題
即使 Maven 或 Gradle 配置正確，IDE 層級的註解處理也常常會阻止 MapStruct 產生映射器實作。許多 IDE 預設會停用此功能。這種情況會導致*MapperImpl檔案缺失、bean 建立失敗以及 IDE 中出現編譯錯誤。
為了解決此類問題，我們在 IDE 設定中啟用註解處理，以便 MapStruct 可以自動產生所需的映射器實作。
5. 結論
本文探討了 MapStruct 的@Mapper註解如何與 Spring bean 建立過程交互，以及為什麼 mapper 實作有時會在應用程式啟動時載入不正確。 MapStruct 在編譯時產生 mapper 實作，如果 Spring 無法正確偵測到它們，則會發生 bean 錯誤。透過使用元件模型配置@Mapper註解，並確保在建置工具和 IDE 中都啟用註解處理，產生的 mapper 可以無縫整合到 Spring 應用程式上下文中。
此外，解決諸如映射器放置在掃描包之外、與Lombok衝突以及 IDE 中的註解處理問題等常見問題，可以穩定映射層並避免運行時 bean 錯誤。因此，與 Spring 掃描和注入機制相符的正確配置和建置設置，能夠確保映射器 bean 的可靠可用性。
原始碼可在 GitHub 上找到。