Mapstruct 1.3.1升级1.4.1后qualifiedBy匹配自定义@ElementToList限定器报错

问题原因 #

MapStruct 1.4.1版本对自定义限定注解的扫描逻辑、泛型方法匹配规则相比1.3.1做了不兼容调整，可按照以下步骤依次排查解决：

• 检查Mapper接口的@Mapper注解是否配置了uses = ElementToListUtil.class，确保MapStruct注解处理器可以扫描到对应的限定方法，升级依赖时可能误改Mapper配置遗漏该属性
• 调整自定义限定注解@ElementToList的保留策略：将原来的@Retention(RetentionPolicy.SOURCE)改为@Retention(RetentionPolicy.CLASS)。1.4版本的注解处理器在编译阶段读取SOURCE级别的注解时存在识别失败的问题，改为CLASS级别后注解会保留到类文件编译阶段，可被MapStruct正常识别
• 如果调整注解保留策略后仍报错，说明是泛型方法匹配规则变更导致的识别失败，可选择两种方案处理：
  1. 给first方法额外添加@Named("elementToList")注解，同时将@Mapping配置中的qualifiedBy = ElementToList.class改为qualifiedByName = "elementToList"
  2. 针对实际使用场景编写非泛型的转换方法，例如入参为业务对应的源类型、返回值为对应List目标类型的具体转换方法，避免泛型匹配问题

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