MapStruct自定义EnumTransformationStrategy注册后无法识别如何解决

问题排查步骤 #

• 第一步：确认SPI注册文件配置完全正确

  检查resources目录是否被正确标记为项目的资源根目录，SPI文件路径必须严格为META-INF/services/org.mapstruct.ap.spi.EnumTransformationStrategy，大小写完全匹配，不能有多余的后缀（比如.txt）。文件内容仅保留自定义策略的全类名org.mapstruct.custom.spi.StripLowerCaseEnumTransformationStrategy，前后不要有多余空格、换行符。

• 第二步：解决注解处理器类加载顺序问题

  MapStruct是编译期注解处理器，若自定义策略和Mapper写在同一项目中，注解处理器运行时自定义策略还未完成编译，会导致无法加载。推荐解决方案：
  将自定义StripLowerCaseEnumTransformationStrategy单独抽为独立子模块，提前编译该子模块后，在主项目的依赖中同时引入该子模块到普通依赖和注解处理器依赖中。Kotlin项目需确保已引入kapt插件，Gradle配置示例如下：

  plugins {
      kotlin("jvm") version "你的Kotlin版本"
      kotlin("kapt") version "你的Kotlin版本"
  }
  
  dependencies {
      // 普通业务依赖
      implementation("org.mapstruct:mapstruct:1.4.2.Final")
      implementation(project(":你的自定义策略子模块名"))
      // 注解处理器依赖
      kapt("org.mapstruct:mapstruct-processor:1.4.2.Final")
      kapt(project(":你的自定义策略子模块名"))
  }
  

• 第三步：检查依赖版本一致性

  确保项目中所有MapStruct相关依赖（包括mapstruct、mapstruct-processor）版本完全统一为1.4.2.Final，无版本混合情况。

• 第四步：清理缓存全量编译

  执行项目clean任务后重新全量构建，IDEA用户可同时执行「Invalidate Caches」操作清理IDE缓存后重启再编译。

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