Java 17下MapStruct 1.3.1在IntelliJ测试报错及版本适配咨询

问题背景 #

• 原技术栈：Java 11 + MapStruct 1.3.1
• 升级后环境：Java 17
• 三类测试场景：
  • 场景1：IntelliJ中直接运行测试用例MyTestMethod，抛出错误：

    java: Supported source version 'RELEASE_6' from annotation processor 'org.mapstruct.ap.MappingProcessor' less than -source '17'

  • 场景2：执行Maven命令 mvn test -Dtest="MyTestClass#MyTestMethod" 运行同一测试，执行成功
  • 场景3：将MapStruct版本更换为1.5.5.Final后，场景1的测试可正常运行

问题解答 #

1. 是否必须升级至MapStruct 1.5.5.Final？适配要点有哪些？ #

必须升级。MapStruct 1.3.1是2019年发布的版本，原生不支持Java 17，其注解处理器默认仅兼容到Java 6，与Java 17的编译参数存在根本性冲突。

适配要点：

• 依赖更新：将MapStruct的mapstruct和mapstruct-processor依赖版本统一改为1.5.5.Final，groupId保持org.mapstruct不变
• 注解兼容性检查：1.5.x版本对部分注解做了优化（如@Mapping的expression属性支持更简洁语法），但常规注解（@Mapper、@Mapping等）无需大面积修改，旧代码可直接兼容
• 编译插件配置：确保Maven Compiler Plugin（或Gradle对应插件）的annotationProcessorPaths正确引入MapStruct处理器，避免与其他注解处理器产生依赖冲突
• 移除冗余配置：如果之前为适配高版本Java添加过强制指定注解处理器source版本的编译参数，可直接移除这些临时兼容补丁

2. 为何升级MapStruct到1.5.5.Final后场景1能正常运行？ #

核心原因是MapStruct 1.5.x版本正式完成了Java 17的兼容性适配：

• 注解处理器版本适配：1.5.5.Final的MappingProcessor已更新对Java版本的识别逻辑，能够兼容-source 17的编译参数，不会再抛出版本不匹配的错误
• IDE编译逻辑匹配：IntelliJ直接运行测试时，会直接调用项目配置的注解处理器进行实时编译，旧版本处理器不支持Java 17导致编译失败；升级后处理器适配了Java 17的编译规则，因此测试可正常执行
• Maven命令执行成功的原因：Maven运行时可能通过Compiler Plugin的配置，间接为旧版本处理器指定了兼容的source版本，实现了临时兼容，但这种兼容在IDE直接编译的场景下不生效，升级MapStruct后则从根源解决了版本兼容问题

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