升级MapStruct至1.4.2.Final时@Named映射方法无法识别报错

问题背景 #

• 升级操作：将项目MapStruct依赖从1.2.0.Final升级至1.4.2.Final，普通映射逻辑运行正常，仅单个复杂抽象类映射器编译阶段抛出异常
• 改造约束：不拆分该映射器为多个独立类，避免额外改造成本影响项目进度
• 初始误判：怀疑问题由Spring AOP代理导致

问题复现代码 #

@Mapper(componentModel = "spring")
public abstract class CustomMapper{

    @Named("mapTestla")
    @Mapping(target = "f", source = "t.f") 
    public abstract TestlaDTO mapTestla(Testla t) {}

    @Named("mapBar")
    @Mapping(target = "t", source = "b.t", qualifiedByName = "mapTestla") 
    public abstract BarDTO mapBar(Bar b) {}

    @Mappings({
        @Mapping(target = "a", source = "f.a"), 
        @Mapping(target = "b", source = "f.b", qualifiedByName = "mapBar")
    })
    public abstract FooDTO mapFoo(Foo f) {}

}

// 业务实体定义
class Foo {
    String a;
    Bar b;
}
class Bar {
    Tesla t;
}
class Testla {
    String f;
}

// DTO定义
class FooDTO {
    String a;
    Bar b;
}
class BarDTO {
    TeslaDTO t;
}
class TestlaDTO {
    String f;
}

编译报错信息 #

Qualifier error. No method found annotated with @Named#value: [ mapBar]
Qualifier error. No method found annotated with @Named#value: [ mapTestla]

问题根因 #

该问题和Spring AOP完全无关。MapStruct的注解扫描、代码生成逻辑全部在Java编译阶段执行，Spring容器、AOP代理逻辑在编译期不会介入，不可能影响MapStruct的方法识别逻辑。
真正原因是MapStruct版本迭代带来的默认行为变更：1.2.0版本默认会扫描当前抽象映射器类内部的所有@Named方法作为qualifiedByName的候选匹配项；从1.3.0.Beta2版本开始，校验逻辑收紧，如果抽象类映射器需要在类内通过qualifiedByName引用自身的@Named方法，必须显式将当前类配置到@Mapper的uses属性中，否则编译期不会将类自身的方法纳入候选池，直接抛出找不到匹配方法的错误。
另外示例代码中存在几处类型拼写/定义笔误，也可能触发同类报错：

• Bar类中t属性类型为Tesla，但mapTestla方法入参类型为Testla
• FooDTO中b属性类型为实体类Bar，而非映射目标类型BarDTO

可行解决方案 #

最小改动方案仅需修改@Mapper注解配置，不需要拆分映射器、不需要调整原有映射方法逻辑，改动成本极低：

// 新增uses = CustomMapper.class 显式声明自引用
@Mapper(componentModel = "spring", uses = CustomMapper.class)
public abstract class CustomMapper{
    // 原有所有映射方法保持不变即可
}

该配置会让MapStruct在编译期将当前映射器类纳入方法扫描范围，和1.2.0版本的默认行为一致，可直接解决@Named方法找不到的问题。
如果修改配置后仍报错，同步修正代码中提到的类型不匹配笔误即可。

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