MapStruct高级映射技巧：解决多源属性到单一目标字段的歧义

本文探讨了在使用mapstruct进行jpa实体与dto转换时，如何处理将不同源实体属性映射到dto同一目标字段的场景。针对因存在多个相似映射方法而导致的歧义错误，文章详细介绍了如何通过结合使用`@named`注解为映射方法命名，以及`@iterablemapping(qualifiedbyname)`指定列表转换时使用的具体映射方法，从而有效解决歧义问题，实现灵活且清晰的代码映射逻辑。

MapStruct中多源属性到单一目标字段的映射策略

在现代Java应用开发中，JPA实体（Entity）与数据传输对象（DTO）之间的转换是常见的操作。MapStruct作为一个强大的代码生成器，极大地简化了这一过程。然而，当我们需要根据特定条件将JPA实体中不同的源属性映射到DTO的同一个目标字段时，会遇到一些挑战。本文将深入探讨如何使用MapStruct的@Named和@IterableMapping注解来优雅地解决这种“条件映射”以及由此引发的歧义问题。

场景描述

假设我们有一个JPA实体CandidateRecommendationJpa，它包含两个CandidateJpa类型的关联字段：candidateSender（推荐发起人）和candidateReceiver（推荐接收人）。

public class CandidateRecommendationJpa extends AuditingEntityJpa {
  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  @Column(name = "ID_CANDIDATO_RECOMENDACION", nullable = false)
  private Integer id;

  @ManyToOne
  @JoinColumn(name = "ID_CANDIDATO_EMISOR", nullable = false)
  private CandidateJpa candidateSender;

  @ManyToOne
  @JoinColumn(name = "ID_CANDIDATO_RECEPTOR", nullable = false)
  private CandidateJpa candidateReceiver;
}

我们希望将其映射到一个简化的DTO CandidateRecommendation，该DTO中只有一个Candidate字段。根据业务需求，这个candidate字段可能需要从candidateSender映射，也可能需要从candidateReceiver映射。

@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
@Builder
@EqualsAndHashCode
public class CandidateRecommendation {
  private Integer id;   
  private Candidate candidate; // 此字段可能来自candidateSender或candidateReceiver
}

初步尝试与遇到的问题

为了实现上述需求，我们可能会在MapStruct映射器中定义两个独立的映射方法：一个将candidateSender映射到candidate，另一个将candidateReceiver映射到candidate。

@Mapper(componentModel = "spring")
public interface CandidateRecommendationJpaMapper {

  // 映射candidateSender到DTO的candidate字段
  @Mapping(target = "candidate.id", source = "candidateSender.id")
  @Mapping(target = "candidate.name", source = "candidateSender.name")
  @Mapping(target = "candidate.login", source = "candidateSender.employee.login")
  CandidateRecommendation toModel(CandidateRecommendationJpa jpa);

  // 映射candidateReceiver到DTO的candidate字段
  @Mapping(target = "candidate.id", source = "candidateReceiver.id")
  @Mapping(target = "candidate.name", source = "candidateReceiver.name")
  @Mapping(target = "candidate.login", source = "candidateReceiver.employee.login")
  CandidateRecommendation toReceiverModel(CandidateRecommendationJpa jpa); // 注意这里为了区分，改名为toReceiverModel

  // 尝试映射列表
  List toModels(List jpa);
  List toReceiverModels(List jpa);
}

当我们尝试编译上述代码时，MapStruct会抛出类似以下的错误：

Ambiguous mapping methods found for mapping collection element to CandidateRecommendation: CandidateRecommendation toModel(CandidateRecommendationJpa jpa), CandidateRecommendation toReceiverModel(CandidateRecommendationJpa jpa)

这个错误表明，当MapStruct尝试为List到List的转换找到合适的元素映射方法时，它发现了两个都可以将CandidateRecommendationJpa转换为CandidateRecommendation的方法（toModel和toReceiverModel），因此无法确定应该使用哪一个。

小艺

华为公司推出的AI智能助手

下载

解决方案：使用@Named和@IterableMapping

为了解决这种歧义，MapStruct提供了@Named和@IterableMapping注解。

1. @Named注解：用于为单个映射方法指定一个唯一的名称。这使得我们可以在需要时通过名称引用特定的映射逻辑。
2. @IterableMapping(qualifiedByName = "...")注解：当进行集合（如List）映射时，此注解允许我们通过qualifiedByName属性明确指定应该使用哪个具名（@Named）的元素映射方法。

下面是应用这些注解后的MapStruct映射器代码：

import org.mapstruct.IterableMapping;
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.Named;
import org.mapstruct.factory.Mappers;

import java.util.List;

@Mapper(componentModel = "spring")
public interface CandidateRecommendationJpaMapper {

    CandidateRecommendationJpaMapper INSTANCE = Mappers.getMapper(CandidateRecommendationJpaMapper.class);

    /**
     * 将CandidateRecommendationJpa映射为DTO，其中DTO的candidate字段来源于candidateSender。
     * 使用@Named("toSenderModel")为其指定唯一名称。
     */
    @Named("toSenderModel")
    @Mapping(target = "candidate.id", source = "candidateSender.id")
    @Mapping(target = "candidate.name", source = "candidateSender.name")
    @Mapping(target = "candidate.login", source = "candidateSender.employee.login")
    CandidateRecommendation toSenderModel(CandidateRecommendationJpa jpa);

    /**
     * 将CandidateRecommendationJpa映射为DTO，其中DTO的candidate字段来源于candidateReceiver。
     * 使用@Named("toReceiverModel")为其指定唯一名称。
     */
    @Named("toReceiverModel")
    @Mapping(target = "candidate.id", source = "candidateReceiver.id")
    @Mapping(target = "candidate.name", source = "candidateReceiver.name")
    @Mapping(target = "candidate.login", source = "candidateReceiver.employee.login")
    CandidateRecommendation toReceiverModel(CandidateRecommendationJpa jpa);

    /**
     * 将CandidateRecommendationJpa列表映射为DTO列表，其中每个DTO的candidate字段都来源于candidateSender。
     * 通过@IterableMapping(qualifiedByName = "toSenderModel")明确指定使用toSenderModel方法进行元素映射。
     */
    @IterableMapping(qualifiedByName = "toSenderModel")
    List toSenderModels(List jpa);

    /**
     * 将CandidateRecommendationJpa列表映射为DTO列表，其中每个DTO的candidate字段都来源于candidateReceiver。
     * 通过@IterableMapping(qualifiedByName = "toReceiverModel")明确指定使用toReceiverModel方法进行元素映射。
     */
    @IterableMapping(qualifiedByName = "toReceiverModel")
    List toReceiverModels(List jpa);
}

通过上述修改，我们为每个单对象映射方法（toSenderModel和toReceiverModel）分别指定了唯一的名称。然后，在列表映射方法（toSenderModels和toReceiverModels）上，我们使用@IterableMapping并结合qualifiedByName属性，明确告诉MapStruct在处理列表中的每个元素时，应该调用哪个具名的单对象映射方法。这样就彻底消除了歧义，使得MapStruct能够正确生成代码。

总结与注意事项

• @Named的用途：当存在多个方法可以将相同源类型映射到相同目标类型，且这些方法在逻辑上有所区别时，使用@Named为它们提供唯一的标识符。这在处理条件映射、策略模式映射或在特定上下文中需要不同映射逻辑时非常有用。
• @IterableMapping(qualifiedByName)的用途：专门用于解决集合类型映射时的歧义。它允许你精确控制集合中每个元素的转换逻辑，避免MapStruct因找不到唯一匹配的元素映射方法而报错。
• 可读性与维护性：这种方法不仅解决了技术问题，还提高了代码的可读性和可维护性。通过具名映射，其他开发者可以清楚地知道每个映射方法和列表转换的具体意图。
• 避免过度使用：虽然@Named和@IterableMapping功能强大，但并非所有映射场景都需要它们。只有当确实存在映射歧义或需要明确区分不同映射策略时，才应考虑使用。
• 与Spring集成：如果componentModel设置为spring，MapStruct生成的映射器将作为Spring组件，可以被Spring容器管理和注入，方便在服务层使用。

通过掌握@Named和@IterableMapping这两个MapStruct高级特性，开发者可以更灵活、更精确地控制复杂的对象映射逻辑，有效应对多源属性到单一目标字段的条件映射场景，从而构建出更加健壮和可维护的应用程序。