Java 17 + Spring Boot 3.2.3下MapStruct @Mapper无法生成Bean求助

1. 确认MapStruct版本与Spring Boot 3.x兼容 #

Spring Boot 3.x必须搭配MapStruct 1.5.3.Final及以上版本（推荐1.5.5.Final），旧版本处理器不支持Java 17和Spring Boot 3的新特性。检查pom.xml中的依赖：

<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>

2. 修正Maven编译器插件的注解处理器配置 #

Java 17下需指定release为17，若搭配Lombok还需添加绑定依赖，且MapStruct处理器要放在Lombok之后避免冲突：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.11.0</version> <!-- 需支持Java17的插件版本 -->
    <configuration>
        <release>17</release>
        <annotationProcessorPaths>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>1.18.30</version> <!-- 兼容Java17的Lombok版本 -->
            </path>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok-mapstruct-binding</artifactId>
                <version>0.2.0</version>
            </path>
            <path>
                <groupId>org.mapstruct</groupId>
                <artifactId>mapstruct-processor</artifactId>
                <version>1.5.5.Final</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

3. 验证Mapper接口的Spring组件配置 #

确保@Mapper注解的componentModel参数拼写正确（小写spring），且自动生成的实现类带有@Component注解：

@Mapper(componentModel = "spring")
public interface UserMapper {
    // 映射方法定义
}

若生成的UserMapperImpl无@Component，说明注解处理器未正常工作，需重新编译。

4. 检查Spring组件扫描范围 #

确认com.abc.portal.mapper包被Spring组件扫描覆盖：

• 启动类若在com.abc.portal包下，默认会扫描所有子包；
• 否则在启动类添加@ComponentScan(basePackages = "com.abc.portal")。

5. 彻底清理并重新编译 #

执行命令清理缓存后重新构建：

mvn clean install -DskipTests

同时清理IDE缓存（比如IntelliJ IDEA执行File -> Invalidate Caches... -> Invalidate and Restart），避免IDE未加载最新生成的实现类。

6. 解决同名Mapper的注入冲突 #

若存在不同包下的同名UserMapper，需用@Qualifier明确指定Bean名称：

@Service
public class UserService {
    @Autowired
    @Qualifier("userMapperImpl") // 对应自动生成的Bean名称（接口名+Impl）
    private UserMapper myMapper;
}

7. 模块化项目的模块配置调整 #

若项目使用Java模块化（含module-info.java），需开放Mapper包给MapStruct和Spring：

module com.abc.portal {
    requires org.mapstruct;
    requires org.springframework.context;
    
    opens com.abc.portal.mapper to org.mapstruct, org.springframework.context;
    exports com.abc.portal.mapper;
}

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