MapStruct映射报错：参数account无contact.holders.emails属性排查

问题核心 #

你遇到的情况是：用MapStruct转换跨版本领域类时，源类的emails属性来自超类，通过Lombok生成getter/setter，添加@Mapping指定属性路径后，编译报错提示找不到该属性，但属性实际存在。

大概率是这几个原因，而非MapStruct的bug #

1. Lombok与MapStruct的编译顺序冲突
   MapStruct是编译时注解处理器，需要读取类的完整元数据（包括getter/setter）。如果Lombok的注解处理在MapStruct之后执行，MapStruct解析类时还看不到Lombok生成的超类属性访问器，就会报错说属性不存在。

2. 属性路径写法的小问题
   虽然你确认路径正确，但有时候MapStruct对嵌套超类属性的解析需要更明确的层级，或者你的路径写法没有匹配到实际的getter方法名（比如emails的getter是getEmails()，路径是否正确对应）。

3. MapStruct 1.6.x对超类属性的解析限制
   部分场景下，1.6.x版本对深层嵌套的超类属性识别不够完善，升级到更高版本（比如1.7.0）可能解决。

解决步骤 #

1. 调整编译顺序，确保Lombok先处理 #

如果用Maven，在pom.xml的annotationProcessorPaths里把Lombok放在MapStruct前面，或者引入lombok-mapstruct-binding来绑定两者的处理顺序：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>11</source>
                <target>11</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>${lombok.version}</version>
                    </path>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${mapstruct.version}</version>
                    </path>
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok-mapstruct-binding</artifactId>
                        <version>0.2.0</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

Gradle的话，在build.gradle里调整注解处理器的顺序，把Lombok放在前面。

2. 验证属性路径与getter匹配 #

确认超类中emails的getter是getEmails()（Lombok默认生成的规则），@Mapping的source路径要严格对应：

@Mapper(componentModel = "spring")
public interface AccountConverter {
    // 确认source路径完全匹配getter的层级
    @Mapping(source = "contact.holders.emails", target = "email")
    Version5Account convertToV5(Version6Account source);
}

如果超类的属性是protected，确保MapStruct能访问到（一般public getter没问题）。

3. 升级MapStruct版本 #

尝试把MapStruct升级到1.7.0或更高版本，新版本对超类属性的解析逻辑更完善，能更好识别嵌套超类的属性。

4. 显式指定超类类型（可选） #

如果上述方法都无效，可以在映射器中显式指定超类的类型，帮助MapStruct识别：

@Mapper(componentModel = "spring")
public interface AccountConverter {
    @Mapping(source = "holders.emails", target = "email")
    Version5Account convertToV5(Version6Account source);

    // 显式定义超类之间的转换，帮助MapStruct识别属性
    default HolderV5 mapHolder(HolderV6 source) {
        return Mappers.getMapper(HolderConverter.class).convertToV5(source);
    }
}

@Mapper
interface HolderConverter {
    @Mapping(source = "emails", target = "email")
    HolderV5 convertToV5(HolderV6 source);
}

总结 #

这个问题基本是编译顺序配置或路径写法的小问题，而非MapStruct的bug。优先调整Lombok和MapStruct的编译顺序，大部分场景下都能解决。

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