Mapstruct映射报错及DTO转换字段全空问题求助

一、解决"源参数中不存在名为'category.id'的属性"错误 #

出现这个编译错误，直接排查以下几点：

• 检查实体Getter方法：确保Product实体有getCategory()方法，同时Category实体有getId()方法。MapStruct完全依赖JavaBean规范的Getter/Setter识别属性，缺任意一个都会导致路径无法解析。
• 确认Mapper方法参数类型：Mapper方法必须明确参数类型为Product，比如ProductDto convert(Product product)，如果写成convert(Object product)，MapStruct无法解析属性结构。
• 核对参数注解匹配：如果Mapper方法用了@Param注解，比如@Mapping(source = "prod.category.id", target = "categoryId")，方法参数必须对应@Param("prod") Product prod，否则属性路径会匹配失败。

二、解决移除注解后DTO全字段为null的问题 #

这种情况说明MapStruct未生成正确的映射逻辑，按步骤排查：

• 匹配MapStruct与Spring Boot版本：Spring Boot 3.4.5建议搭配1.5.5.Final或更高版本的MapStruct，避免版本兼容问题。
  Maven依赖示例：

  <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 Kotlin DSL示例：

  implementation("org.mapstruct:mapstruct:1.5.5.Final")
  annotationProcessor("org.mapstruct:mapstruct-processor:1.5.5.Final")
  

• 确保注解处理器配置正确：
  若使用Lombok，必须添加lombok-mapstruct-binding解决两者代码生成冲突，Maven插件配置示例：

  <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-compiler-plugin</artifactId>
      <version>3.11.0</version>
      <configuration>
          <source>17</source>
          <target>17</target>
          <annotationProcessorPaths>
              <path>
                  <groupId>org.mapstruct</groupId>
                  <artifactId>mapstruct-processor</artifactId>
                  <version>1.5.5.Final</version>
              </path>
              <path>
                  <groupId>org.projectlombok</groupId>
                  <artifactId>lombok</artifactId>
                  <version>1.18.30</version>
              </path>
              <path>
                  <groupId>org.projectlombok</groupId>
                  <artifactId>lombok-mapstruct-binding</artifactId>
                  <version>0.2.0</version>
              </path>
          </annotationProcessorPaths>
      </configuration>
  </plugin>
  

• 检查字段名匹配规则：MapStruct默认映射同名字段，若实体字段是productName、DTO是product_name这类格式差异，需手动添加@Mapping注解，或在Mapper接口上配置命名策略实现自动转换。
• 清理缓存重新构建：执行mvn clean install（Maven）或gradle clean build（Gradle），清除编译缓存后重新生成MapStruct实现类。

额外验证步骤 #

查看生成的实现类：在target/generated-sources/annotations（Maven）或build/generated/sources/annotationProcessor/java/main（Gradle）路径下找到ProductMapperImpl，检查内部映射逻辑是否正确。如果找不到该类，说明注解处理器未正常工作，回到依赖配置环节排查。

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