MapStruct嵌套类与列表对象映射异常问题求助

你直接用@Mapping(source = "addresses.postalCode", target = "addresses.zipCode")的写法错误，因为addresses是集合类型，MapStruct无法直接通过这种路径语法处理集合内的字段映射。正确的做法是为嵌套的子对象单独定义映射器，再让主映射器复用这些子映射逻辑。

步骤1：定义子对象的映射接口 #

先为CustAddress到目标地址类、Person到目标Person类创建单独的映射接口：

// 源地址类到目标地址类的映射
@Mapper
public interface AddressMapper {
    AddressMapper INSTANCE = Mappers.getMapper(AddressMapper.class);

    @Mapping(source = "postalCode", target = "zipCode")
    DestinationAddress mapCustAddressToDestination(CustAddress source);
}

// 源Person到目标Person的映射
@Mapper
public interface PersonMapper {
    PersonMapper INSTANCE = Mappers.getMapper(PersonMapper.class);

    @Mapping(source = "jobTitle", target = "workTitle")
    DestinationPerson mapPersonToDestination(Person source);
}

步骤2：在主映射器中关联子映射 #

在ClassSource到ClassDestination的主映射接口中，通过uses属性引入子映射器，MapStruct会自动处理集合和嵌套对象的转换：

@Mapper(uses = {AddressMapper.class, PersonMapper.class})
public interface ClassMapper {
    ClassMapper INSTANCE = Mappers.getMapper(ClassMapper.class);

    // 无需额外配置addresses和person的映射，MapStruct会自动调用子映射器逻辑
    ClassDestination mapClassSourceToDestination(ClassSource source);
}

关键说明 #

• 处理集合映射时，MapStruct会自动识别单个对象的映射方法（比如AddressMapper中的单地址转换方法），循环调用完成集合转换。
• @Mapper(uses = ...)用于让主映射器复用其他映射器的规则，避免重复编写嵌套字段的映射配置。
• 若源类和目标类的字段名称大部分一致，仅需单独配置差异字段（如postalCode→zipCode），其余字段MapStruct会自动匹配。

异常排查要点 #

如果仍抛出异常，检查以下内容：

• 确认所有源类、目标类的getter/setter方法完整（MapStruct依赖这些方法访问字段）。
• 子映射接口的方法签名正确，参数和返回类型与对应源/目标对象匹配。
• 若使用Spring集成模式（@Mapper(componentModel = "spring")），确保所有映射器被Spring正确扫描。

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