新增MapStruct包引发Spring Boot组件注入与Controller异常问题

问题场景 #

在Spring Boot应用中新增包含MapStruct映射器的包后，出现以下问题：

• Service里用@Autowired注入的UtenteMapper字段始终为null，无法正常工作。
• 给主类PaniECumpanagghiuApplicationConfiguration添加@ComponentScan("PaniECumpanagghiu.PaniECumpanagghiu.Mappers")后，Mapper能正常运行，但所有API调用都返回404，Controller完全没触发。
• 尝试把所有包都加入@ComponentScan的扫描范围，Mapper又回到无法注入的状态。
• 注释掉新包的所有引用，简化API只返回字符串"Ciao"，Controller又能正常响应。

核心问题分析 #

1. 包扫描规则冲突：@SpringBootApplication默认会扫描主类所在包及其所有子包。手动指定@ComponentScan会覆盖这个默认规则——只扫Mappers包的话，Controller所在包没被扫描，自然返回404；如果指定多个包时格式不对，又会导致Mapper没被正确识别。
2. MapStruct映射器未被Spring管理：如果映射器接口没加@Mapper(componentModel = "spring")注解，MapStruct生成的实现类不会被Spring注册为Bean，自然无法通过@Autowired注入。
3. 编译配置不匹配：pom.xml里maven-compiler-plugin的source和target版本设为1.8，但项目用的是Java 22，版本不匹配会导致映射器代码生成异常，进而无法被Spring识别。
4. Lombok与MapStruct注解处理器冲突：项目用了Lombok，但pom里没把Lombok的注解处理器加入annotationProcessorPaths，可能影响MapStruct的代码生成。

分步解决方案 #

1. 修正主类的包扫描配置

优先用@SpringBootApplication的默认扫描规则：把主类放在项目的根包（比如PaniECumpanagghiu），这样默认会扫描所有子包（包括Mappers、Controllers、Services），不需要手动加@ComponentScan。

如果必须手动指定扫描范围，要把所有需要的包都列出来：

@SpringBootApplication
@ComponentScan(basePackages = {
    "PaniECumpanagghiu.PaniECumpanagghiu.Mappers",
    "PaniECumpanagghiu.PaniECumpanagghiu.Controllers",
    "PaniECumpanagghiu.PaniECumpanagghiu.Services",
    "PaniECumpanagghiu.PaniECumpanagghiu.Repositories" // 按需添加其他包
})
public class PaniECumpanagghiuApplicationConfiguration {
    public static void main(String[] args) {
        SpringApplication.run(PaniECumpanagghiuApplicationConfiguration.class, args);
    }
}

2. 让MapStruct映射器被Spring管理

在UtenteMapper接口上添加@Mapper注解，并指定componentModel = "spring"，这样MapStruct生成的实现类会自动被Spring注册为Bean：

import org.mapstruct.Mapper;

@Mapper(componentModel = "spring")
public interface UtenteMapper {
    // 定义你的映射方法，比如：
    // UtenteDto toDto(Utente entity);
    // Utente toEntity(UtenteDto dto);
}

3. 修正pom.xml的编译配置

• 把maven-compiler-plugin的source和target版本改成和项目java.version一致的22，避免版本不匹配。
• 把Lombok的注解处理器加入annotationProcessorPaths，解决和MapStruct的冲突。

修正后的pom.xml关键部分：

<properties>
    <java.version>22</java.version>
    <org.mapstruct.version>1.6.2</org.mapstruct.version>
    <lombok.version>1.18.32</lombok.version> <!-- 可指定Lombok版本，或用Spring Boot父依赖的默认版本 -->
</properties>

<!-- ... 其他依赖保持不变 ... -->

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <excludes>
                    <exclude>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                    </exclude>
                </excludes>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <source>${java.version}</source>
                <target>${java.version}</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${org.mapstruct.version}</version>
                    </path>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${lombok.version}</version>
                    </path>
                    <!-- 可选：添加Lombok与MapStruct的绑定依赖，解决两者注解兼容问题 -->
                    <!--
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok-mapstruct-binding</artifactId>
                        <version>0.2.0</version>
                    </path>
                    -->
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

4. 清理并重新构建项目

执行Maven命令清理旧的编译文件，重新生成映射器代码：

mvn clean install

运行应用后，Mapper应该能正常注入，Controller也能响应API请求了。

内容的提问来源于stack exchange，提问作者Rosario Di Mari