MapStruct 1.5.x搭配Lombok在Gradle下升级后报未知属性编译错误

这个报错本质是MapStruct 1.5.x系列调整了注解处理器属性探测逻辑，和1.4.2.Final的默认行为存在不兼容导致，按以下步骤调整即可修复：

核心不兼容点说明 #

• 1.5.x 对Lombok版本的最低兼容要求为1.18.22，但1.18.22~1.18.25版本存在注解处理器元数据传递bug，会导致MapStruct无法读取Lombok生成的getter/setter方法
• 1.5.x 默认优先识别类的Builder构造逻辑，不会主动扫描链式setter（返回值为当前类实例而非void的set方法），和Lombok @Accessors(chain = true) 生成的方法默认不匹配
• 1.5.x 不再自动继承Gradle配置里的注解处理器路径，部分场景下会出现处理器加载不全的问题

具体修复步骤 #

第一步：调整依赖版本匹配 #

将build.gradle中的版本配置调整为经过验证的兼容组合，不要随意混搭版本：

project.ext {
  sdaseVersion = '2.53.1'
  lombokVersion = '1.18.30' // 升级到1.18.26及以上修复元数据传递bug
  mapStructVersion = '1.5.2.Final'
  lombokMapStructBindingVersion = '0.2.0' // 该版本无需升级，全兼容1.5.x系列
}

dependencies {
  // 其他原有依赖保持不变

  implementation "org.mapstruct:mapstruct:${mapStructVersion}"
  compileOnly "org.projectlombok:lombok:${lombokVersion}"

  annotationProcessor "org.projectlombok:lombok:${lombokVersion}"
  annotationProcessor "org.mapstruct:mapstruct-processor:${mapStructVersion}"
  annotationProcessor "org.projectlombok:lombok-mapstruct-binding:${lombokMapStructBindingVersion}"
  // 如果引入了mapstruct-spring-extension等第三方扩展，需同步升级到1.5.2对应版本，否则会出现逻辑冲突
}

注意：不要手动调整三个annotationProcessor的声明顺序，1.5.x版本配合lombok-mapstruct-binding 0.2.0会自动处理加载优先级，手动调整顺序反而可能导致Lombok的属性元数据无法正常传递给MapStruct。

第二步：补充编译配置 #

在build.gradle中补充Java编译任务的配置，显式指定注解处理器路径和兼容参数：

compileJava {
    // 显式指定注解处理器加载路径，避免1.5.x版本处理器加载不全
    options.annotationProcessorPath = configurations.annotationProcessor
    options.compilerArgs += [
        // 未映射目标属性先降级为警告，方便排查具体缺失的字段
        '-Amapstruct.unmappedTargetPolicy=WARN',
        // 如果你使用Spring容器管理Mapper，将下面参数值改为spring，否则保持default
        '-Amapstruct.defaultComponentModel=default'
    ]
}

第三步：适配链式访问器逻辑 #

如果你的实体类使用了Lombok的@Accessors(chain = true)注解，可选择以下任意一种方式适配：

• 单个Mapper适配：在对应@Mapper注解上添加配置，关闭默认的Builder优先探测逻辑

  // 关闭Builder优先探测，让MapStruct直接识别Lombok生成的链式setter
  @Mapper(builder = @Builder(disableBuilder = true))
  public interface UserMapper {
      // 原有映射方法保持不变
  }
  

• 全局适配：在build.gradle的编译参数里追加全局配置，不用逐个修改注解

  options.compilerArgs += [
      // 全局关闭Mapper的Builder探测
      '-Amapstruct.disableBuilder=true'
  ]
  

第四步：全量清理缓存重新构建 #

按顺序执行以下操作，避免旧缓存干扰：

• 执行命令./gradlew --stop 关闭所有后台Gradle守护进程
• 执行命令./gradlew clean build --refresh-dependencies 全量清理构建缓存、刷新依赖
• 打开IDE的缓存清理菜单，选择「Invalidate Caches and Restart」，重启后等Gradle同步完成再触发编译
• 如果使用IntelliJ IDEA，确认设置中Build, Execution, Deployment > Compiler > Annotation Processors已勾选「Enable annotation processing」，且选择「Obtain processors from project classpath」，不要手动指定处理器jar包路径

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