Spring Boot中MapStruct映射所有字段为null的问题排查

问题场景 #

• 技术栈：Spring Boot 3.0.2、Java 17、Lombok 1.18.24、MapStruct 1.5.3.Final、IntelliJ IDEA 2022.2.4 + JPA Buddy 2022.5.4-222
• 现象：实体类使用Lombok @Getter/@Setter生成访问器时，MapStruct生成的Mapper实现中toEntity、toDto、partialUpdate方法无法正确映射字段，所有字段值为null；移除Lombok注解后映射恢复正常。

解决方案 #

1. 调整依赖处理器执行顺序 #

MapStruct需要在Lombok生成访问器之后再生成映射代码，因此必须确保Lombok注解处理器优先于MapStruct执行。

Maven配置（pom.xml）

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.10.1</version>
            <configuration>
                <source>17</source>
                <target>17</target>
                <annotationProcessorPaths>
                    <!-- Lombok处理器放在MapStruct之前 -->
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>1.18.24</version>
                    </path>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>1.5.3.Final</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

Gradle配置（build.gradle）

dependencies {
    implementation 'org.mapstruct:mapstruct:1.5.3.Final'
    // Lombok注解处理器优先声明
    annotationProcessor 'org.projectlombok:lombok:1.18.24'
    annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.3.Final'
    compileOnly 'org.projectlombok:lombok:1.18.24'
}

2. 启用MapStruct对Lombok的显式支持 #

在项目配置中添加MapStruct的Lombok支持参数，确保MapStruct能识别Lombok生成的访问器：

<!-- pom.xml中添加属性配置 -->
<properties>
    <mapstruct.defaultComponentModel>spring</mapstruct.defaultComponentModel>
    <mapstruct.lombok.addon.enabled>true</mapstruct.lombok.addon.enabled>
</properties>

3. IntelliJ IDEA环境配置 #

• 确保Lombok插件已启用：Settings > Plugins中搜索Lombok并确认启用。
• 开启注解处理：Settings > Build, Execution, Deployment > Compiler > Annotation Processors，勾选Enable annotation processing。
• 清理缓存并重建：File > Invalidate Caches...，选择Invalidate and Restart，之后执行Maven/Gradle Clean + Build操作。

4. 检查Lombok注解使用 #

• 确保实体类上的@Getter/@Setter注解生效，可通过IntelliJ的Structure视图查看是否生成了对应的getter/setter方法。
• 尝试替换为@Data注解（包含getter、setter、toString等），避免单独注解遗漏导致的访问器缺失。

问题原因 #

MapStruct生成映射代码时，依赖实体类的getter/setter方法完成字段赋值。如果Lombok的注解处理器晚于MapStruct执行，MapStruct在生成代码时无法识别Lombok后续生成的访问器，会默认认为没有可用的字段读写方法，最终导致映射结果全为null。

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