Spring Boot中MapStruct无法正确映射嵌套DTO问题

常见原因及修复方案 #

1. 未正确声明依赖的Mapper #

确保在IndividualMapper中通过uses属性引入所有嵌套层级需要的Mapper，而非仅用@Autowired注入：

@Mapper(componentModel = "spring", uses = {UserMapper.class, AddressMapper.class, CountryMapper.class})
public interface IndividualMapper {
    IndividualDTO toDto(Individual entity);
}

uses属性是MapStruct识别子Mapper的关键，仅注入不会触发框架调用子Mapper的映射逻辑。

2. 实体与DTO字段名不匹配 #

MapStruct默认按字段名匹配映射，若嵌套层级的字段名不一致，需显式指定映射关系：

@Mapping(source = "user", target = "userDto")
@Mapping(source = "address.country", target = "addressDto.countryDto")
IndividualDTO toDto(Individual entity);

也可在子Mapper中预先定义好对应实体与DTO的映射方法，让父Mapper自动调用。

3. 子Mapper缺少对应映射方法 #

确认所有子Mapper（如UserMapper、AddressMapper）都定义了完整的实体转DTO方法：

@Mapper(componentModel = "spring")
public interface UserMapper {
    UserDTO toDto(User user);
}

子Mapper缺少对应方法时，MapStruct无法生成嵌套字段的映射逻辑，只会创建空对象实例。

4. 构建工具配置异常 #

• Maven：保证mapstruct核心依赖与mapstruct-processor版本一致，且processor的scope为provided：

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

• Gradle：需正确配置注解处理器，确保编译时生成完整的实现类：

dependencies {
    implementation 'org.mapstruct:mapstruct:1.5.5.Final'
    annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.5.Final'
}

配置错误会导致MapStruct无法生成完整的映射逻辑代码。

5. 清理编译缓存 #

IDE缓存或编译残留可能导致生成的Impl类异常，执行以下操作：

• 执行mvn clean install（Maven）或gradle clean build（Gradle）
• 重启IDE并同步项目

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