MapStruct无法为@Mapping注解生成实现代码问题排查

问题背景 #

基于Spring Boot 2.2.0.RELEASE项目，MapStruct整体运行正常，但在处理List类型的嵌套对象映射时，@Mapping注解无法生成对应转换代码。相关依赖配置如下：

implementation 'org.projectlombok:lombok'
annotationProcessor 'org.projectlombok:lombok'
implementation 'org.mapstruct:mapstruct'
annotationProcessor 'org.mapstruct:mapstruct-processor'
implementation 'org.projectlombok:lombok-mapstruct-binding:0.2.0'
annotationProcessor "org.projectlombok:lombok-mapstruct-binding:0.2.0"

涉及实体与DTO结构：

• UserEntity.java

public class UserEntity {
    private String username;
    private Integer userAge;
    private UserAddressEntity userAddressEntity;
}

• UserAddressEntity.java

public class UserAddressEntity {
    private String userAddress;
    private Integer userPhone;
}

• UserAddressDTO.java

public class UserAddressDTO {
    private String userAddress;
    private Integer userPhone;
}

• TargetDTO.java

public class TargetDTO {
    private String username;
    private Integer userAge;
    private UserAddressDTO userAddressDto; 
}

核心问题：当Mapper仅定义List转换方法时，@Mapping注解无法触发嵌套对象的映射逻辑：

@Mapper(componentModel = "spring")
public interface UserEntityMapper {
    @Mapping(source = "userAddressEntity", target = "userAddressDto")
    List<TargetDTO> fromEntityToDto(List<UserEntity> userEntityList);
}

尝试直接映射嵌套字段、引入子Mapper等方式均无效，仅当TargetDTO字段名与UserEntity完全一致时映射正常。

原因分析 #

1. 集合映射的底层逻辑：MapStruct处理List等集合映射时，依赖于单个对象的转换方法。若未显式定义单个UserEntity -> TargetDTO的转换规则，MapStruct自动生成的基础单个转换逻辑不会识别@Mapping中的嵌套映射配置，导致自定义规则失效。
2. 依赖版本兼容性：Spring Boot 2.2.0.RELEASE未指定MapStruct具体版本时，默认拉取的版本可能与lombok-mapstruct-binding:0.2.0存在兼容性问题。

解决方案 #

方案1：显式定义单个对象转换方法 #

在Mapper中先定义单个实体转DTO的方法并添加@Mapping注解，List转换方法会自动复用该逻辑：

@Mapper(componentModel = "spring")
public interface UserEntityMapper {
    // 显式定义单个对象转换，配置嵌套映射规则
    @Mapping(source = "userAddressEntity", target = "userAddressDto")
    TargetDTO fromEntityToDto(UserEntity userEntity);

    // List转换自动复用单个转换逻辑，无需额外添加@Mapping
    List<TargetDTO> fromEntityToDto(List<UserEntity> userEntityList);
}

方案2：统一依赖版本兼容性 #

Spring Boot 2.2.0.RELEASE推荐搭配MapStruct 1.3.1.Final版本（与lombok-mapstruct-binding:0.2.0兼容），修改依赖配置：

implementation 'org.projectlombok:lombok'
annotationProcessor 'org.projectlombok:lombok'
// 指定兼容的MapStruct版本
implementation 'org.mapstruct:mapstruct:1.3.1.Final'
annotationProcessor 'org.mapstruct:mapstruct-processor:1.3.1.Final'
implementation 'org.projectlombok:lombok-mapstruct-binding:0.2.0'
annotationProcessor "org.projectlombok:lombok-mapstruct-binding:0.2.0"

方案3：结合子Mapper实现嵌套转换 #

若需单独拆分嵌套对象的转换逻辑，需确保子Mapper正确定义，且主Mapper的单个转换方法能触发子Mapper调用：

// 子Mapper：处理UserAddressEntity到UserAddressDTO的转换
@Mapper(componentModel = "spring")
public interface UserAddressMapper {
    UserAddressDTO fromEntityToDto(UserAddressEntity entity);
}

// 主Mapper：引入子Mapper，定义单个转换方法
@Mapper(componentModel = "spring", uses = UserAddressMapper.class)
public interface UserEntityMapper {
    @Mapping(source = "userAddressEntity", target = "userAddressDto")
    TargetDTO fromEntityToDto(UserEntity userEntity);

    List<TargetDTO> fromEntityToDto(List<UserEntity> userEntityList);
}

验证方法 #

编译项目后，查看自动生成的UserEntityMapperImpl类，确认单个转换方法中包含嵌套对象的映射代码，例如：

targetDto.setUserAddressDto(userAddressMapper.fromEntityToDto(userEntity.getUserAddressEntity()));

内容的提问来源于stack exchange，提问作者Ali