如何在MapStruct中将String类型源对象映射为UUID类型目标对象？

问题场景 #

源类BuyerInfo的membershipID为String类型，目标类BuyerInfo的membershipID为UUID类型，使用MapStruct映射时触发报错：

无法将属性"String buyerInfo.primaryMembershipID"映射为"UUID buyerInfo.id"。请考虑声明/实现一个映射方法："UUID map(String value)"。

解决方法 #

方法一：自定义转换方法 #

在Mapper接口中添加String转UUID的默认方法，处理空值和非法格式的情况：

@Mapper
public interface BuyerInfoMapper {
    BuyerInfoMapper INSTANCE = Mappers.getMapper(BuyerInfoMapper.class);

    // 自定义String到UUID的转换逻辑
    default UUID stringToUUID(String uuidStr) {
        if (uuidStr == null || uuidStr.isBlank()) {
            return null;
        }
        try {
            return UUID.fromString(uuidStr);
        } catch (IllegalArgumentException e) {
            // 可根据业务需求调整异常处理逻辑，比如返回null或抛自定义业务异常
            throw new RuntimeException("UUID字符串格式无效: " + uuidStr, e);
        }
    }

    // 对象映射方法，MapStruct会自动调用上面的转换方法处理membershipID字段
    BuyerInfo mapToTarget(com.yourpackage.source.BuyerInfo sourceBuyerInfo);
}

方法二：使用@Mapping的expression属性 #

直接在映射注解中嵌入转换逻辑，无需单独定义转换方法：

@Mapper
public interface BuyerInfoMapper {
    BuyerInfoMapper INSTANCE = Mappers.getMapper(BuyerInfoMapper.class);

    @Mapping(
        source = "membershipID",
        target = "membershipID",
        expression = "java( source.getMembershipID() == null || source.getMembershipID().isBlank() ? null : UUID.fromString(source.getMembershipID()) )"
    )
    BuyerInfo mapToTarget(com.yourpackage.source.BuyerInfo sourceBuyerInfo);
}

注意事项 #

• 两个BuyerInfo类需通过包名区分，避免编译时类名冲突；
• 若使用Spring框架，可在@Mapper注解中添加componentModel = "spring"，让Spring管理Mapper实例，无需手动调用Mappers.getMapper()；
• 非法UUID字符串的处理逻辑需结合业务场景调整，避免未捕获的运行时异常影响流程。

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