快捷導(dǎo)航

mapstruct中的@Mapper注解的基本用法

更新時(shí)間：2025年06月13日 11:53:37 作者：有夢(mèng)想的攻城獅

在MapStruct中,@Mapper注解是核心注解之一,用于標(biāo)記一個(gè)接口或抽象類(lèi)為MapStruct的映射器（Mapper）,本文給大家介紹mapstruct中的@Mapper注解的相關(guān)知識(shí),感興趣的朋友一起看看吧

在MapStruct中，@Mapper注解是核心注解之一，用于標(biāo)記一個(gè)接口或抽象類(lèi)為MapStruct的映射器（Mapper）。MapStruct會(huì)在編譯時(shí)自動(dòng)生成該接口的實(shí)現(xiàn)類(lèi)，完成對(duì)象之間的屬性映射。以下是對(duì)@Mapper注解的詳細(xì)解析：

1. 基本用法

@Mapper注解可以單獨(dú)使用，也可以配合其他屬性進(jìn)行配置。以下是一個(gè)簡(jiǎn)單的示例：

import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.factory.Mappers;
@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);
    @Mapping(source = "username", target = "name")
    UserDTO toUserDTO(User user);
}

@Mapper：標(biāo)記接口為MapStruct的映射器。
Mappers.getMapper(UserMapper.class)：獲取MapStruct自動(dòng)生成的映射器實(shí)例。
@Mapping：指定屬性映射規(guī)則（例如將User的username屬性映射到UserDTO的name屬性）。

2. 常用屬性

@Mapper注解支持多種屬性，用于配置映射器的行為：

(1) componentModel

指定生成的映射器實(shí)現(xiàn)類(lèi)的組件模型，便于與其他框架（如Spring、CDI）集成。

可選值： default：默認(rèn)模型，不依賴任何框架。

spring：生成的映射器實(shí)現(xiàn)類(lèi)會(huì)帶有@Component注解，便于Spring管理。
cdi：生成的映射器實(shí)現(xiàn)類(lèi)會(huì)帶有@ApplicationScoped注解，便于CDI管理。
jsr330：生成的映射器實(shí)現(xiàn)類(lèi)會(huì)帶有@javax.inject.Named和@javax.inject.Singleton注解。

示例：

@Mapper(componentModel = "spring")
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);
    // ...
}

(2) uses

指定其他映射器或工具類(lèi)，用于在映射過(guò)程中調(diào)用。

示例：

@Mapper(uses = {DateMapper.class})
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);
    // ...
}

(3) implementationName 和 implementationPackage

implementationName：指定生成的映射器實(shí)現(xiàn)類(lèi)的名稱（默認(rèn)為接口名+Impl）。
implementationPackage：指定生成的映射器實(shí)現(xiàn)類(lèi)的包名（默認(rèn)為接口所在包）。

示例：

@Mapper(implementationName = "CustomUserMapperImpl", implementationPackage = "com.example.mappers")
public interface UserMapper {
    // ...
}

(4) unmappedTargetPolicy

指定當(dāng)目標(biāo)對(duì)象有未映射的屬性時(shí)的處理策略。

可選值：

ERROR：拋出異常（默認(rèn)值）。
WARN：生成警告日志。
IGNORE：忽略未映射的屬性。

示例：

@Mapper(unmappedTargetPolicy = ReportingPolicy.IGNORE)
public interface UserMapper {
    // ...
}

(5) injectionStrategy

指定依賴注入的策略。

可選值：

FIELD：通過(guò)字段注入（默認(rèn)值）。
CONSTRUCTOR：通過(guò)構(gòu)造函數(shù)注入。
METHOD：通過(guò)方法注入。

示例：

@Mapper(componentModel = "spring", injectionStrategy = InjectionStrategy.CONSTRUCTOR)
public interface UserMapper {
    // ...
}

3. 高級(jí)用法

(1) 結(jié)合@MapperConfig

可以通過(guò)@MapperConfig定義全局配置，然后在@Mapper中引用。

示例：

@MapperConfig(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.IGNORE)
public interface CommonMapperConfig {
}
@Mapper(config = CommonMapperConfig.class)
public interface UserMapper {
    // ...
}

(2) 自定義方法

可以在映射器接口中定義自定義方法，MapStruct會(huì)調(diào)用這些方法完成復(fù)雜的映射邏輯。

示例：

@Mapper
public interface UserMapper {
    UserMapper INSTANCE = Mappers.getMapper(UserMapper.class);
    @Mapping(target = "fullName", expression = "java(user.getFirstName() + \" \" + user.getLastName())")
    UserDTO toUserDTO(User user);
    default String formatDate(Date date) {
        // 自定義日期格式化邏輯
        return new SimpleDateFormat("yyyy-MM-dd").format(date);
    }
}

4. 注意事項(xiàng)

依賴配置：

確保項(xiàng)目中包含MapStruct的依賴和注解處理器（mapstruct和mapstruct-processor）。
如果使用Lombok，確保Lombok的版本兼容，并在構(gòu)建工具（如Maven或Gradle）中正確配置。

映射規(guī)則：

如果源對(duì)象和目標(biāo)對(duì)象的屬性名相同，MapStruct會(huì)自動(dòng)映射。
如果屬性名不同，需要通過(guò)@Mapping注解顯式指定。

性能：

MapStruct生成的映射代碼是類(lèi)型安全的，且在編譯時(shí)完成，性能優(yōu)于運(yùn)行時(shí)反射的映射工具（如Apache Commons BeanUtils）。

5. 總結(jié)

@Mapper注解是MapStruct的核心，通過(guò)它可以：

定義映射器接口。
配置映射器的行為（如組件模型、未映射屬性的處理策略等）。
結(jié)合其他注解（如@Mapping）完成復(fù)雜的屬性映射。
與其他框架（如Spring）無(wú)縫集成。

通過(guò)合理使用@Mapper注解及其屬性，可以大大簡(jiǎn)化對(duì)象之間的映射邏輯，提高開(kāi)發(fā)效率和代碼質(zhì)量。

6. 編譯異常處理

針對(duì)MapStruct項(xiàng)目編譯異常問(wèn)題，可從依賴配置、IDE設(shè)置、代碼規(guī)范及版本兼容性四個(gè)維度進(jìn)行排查和解決，以下是具體分析和建議：

現(xiàn)象：缺少必要的注解處理器依賴，如org.mapstruct:mapstruct-processor，導(dǎo)致編譯時(shí)無(wú)法生成Mapper類(lèi)。
解決方案：
- Maven項(xiàng)目：在pom.xml中添加MapStruct核心庫(kù)和處理器依賴，例如：

<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.5.3.Final</version>
</dependency>
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct-processor</artifactId>
    <version>1.5.3.Final</version>
    <scope>provided</scope>
</dependency>

- **Gradle項(xiàng)目**：在`build.gradle`中添加：

implementation 'org.mapstruct:mapstruct:1.5.3.Final'
annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.3.Final'

IDE設(shè)置問(wèn)題

現(xiàn)象：IDE未啟用注解處理器或緩存異常，導(dǎo)致編譯時(shí)無(wú)法正確處理MapStruct注解。
解決方案：
- IntelliJ IDEA：打開(kāi)“File”菜單，選擇“Settings”，導(dǎo)航至“Build, Execution, Deployment” -> “Compiler” -> “Annotation Processors”，勾選“Enable annotation processing”選項(xiàng)，并清理IDE緩存后重新構(gòu)建項(xiàng)目。

代碼規(guī)范問(wèn)題

現(xiàn)象：Mapper接口定義錯(cuò)誤，如方法簽名不匹配或缺少必要注解，導(dǎo)致編譯失敗。
解決方案：
- 驗(yàn)證Mapper接口：確保接口符合MapStruct規(guī)范，例如：

@Mapper
public interface UserMapper {
    UserDto userToUserDto(User user);
}

- **檢查屬性映射**：如果源對(duì)象和目標(biāo)對(duì)象的屬性名不同，需要通過(guò)`@Mapping`注解顯式指定，例如：

@Mapper
public interface UserMapper {
    @Mapping(source = "username", target = "name")
    UserDto userToUserDto(User user);
}

版本兼容性問(wèn)題

現(xiàn)象：MapStruct版本與其他依賴（如Lombok）不兼容，導(dǎo)致編譯異常。
解決方案：
- 升級(jí)MapStruct版本：嘗試升級(jí)至最新穩(wěn)定版本，例如：

<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.6.0.Final</version>
</dependency>

- **解決Lombok沖突**：如果項(xiàng)目中同時(shí)使用Lombok和MapStruct，特別是使用Lombok的`@Builder`注解時(shí)，可能導(dǎo)致`@AfterMapping`不生效。對(duì)于Lombok版本1.18.16或更高版本，需添加`lombok-mapstruct-binding`依賴：

<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok-mapstruct-binding</artifactId>
    <version>0.2.0</version>
</dependency>

其他可能的問(wèn)題及解決方案

未映射的目標(biāo)屬性：檢查源對(duì)象和目標(biāo)對(duì)象，確保存在對(duì)應(yīng)的屬性，或使用@Mapping(target = "property", ignore = true)忽略不需要映射的屬性。
枚舉類(lèi)型映射：自定義映射方法，例如：

@Mapper
public interface EnumConverter {
    default TargetEnum toTargetEnum(SourceEnum sourceEnum) {
        if (sourceEnum == null) {
            return null;
        }
        switch (sourceEnum) {
            case SOURCE_VALUE1:
                return TargetEnum.TARGET_VALUE1;
            case SOURCE_VALUE2:
                return TargetEnum.TARGET_VALUE2;
            default:
                throw new IllegalArgumentException("Unknown enum type: " + sourceEnum);
        }
    }
}