Spring Boot+MapStruct多层一对多循环依赖栈溢出问题求助

针对你遇到的Document与DocumentType双向一对一关联导致的循环映射问题，结合MapStruct 1.5.1的特性，提供以下几种可行方案：

1. 为双向关联实体编写自定义映射逻辑，手动切断循环 #

最直接的方式是针对Document和DocumentType这对循环依赖的实体，自定义映射方法，避免互相引用完整对象：

示例代码： #

@Mapper(componentModel = "spring")
public interface DocumentTypeMapper {
    // 映射DocumentType到DTO时，指定documents的映射方式
    @Mapping(target = "documents", qualifiedByName = "mapDocumentWithoutType")
    DocumentTypeDTO toDto(DocumentType documentType);

    // 自定义Document映射方法，忽略documentType字段
    @Named("mapDocumentWithoutType")
    default DocumentDTO mapDocumentWithoutType(Document document) {
        if (document == null) return null;
        DocumentDTO dto = new DocumentDTO();
        dto.setId(document.getId());
        dto.setTitle(document.getTitle());
        // 不设置documentType字段，彻底切断循环
        return dto;
    }
}

// 在ProjectMapper中关联子映射器
@Mapper(componentModel = "spring", uses = {DocumentClassMapper.class})
public interface ProjectMapper {
    ProjectDTO toDto(Project project);
}

@Mapper(componentModel = "spring", uses = {DocumentTypeMapper.class})
public interface DocumentClassMapper {
    DocumentClassDTO toDto(DocumentClass documentClass);
}

这种方式通过显式控制Document到DocumentDTO的映射内容，直接避免了反向引用DocumentType导致的递归调用。

2. 使用MapStruct的@Context上下文对象跟踪已映射实例 #

通过自定义上下文类，记录已经完成映射的对象，防止重复递归映射：

示例代码： #

// 循环避免上下文类
public class CycleAvoidingMappingContext {
    private final Map<Object, Object> mappedInstances = new IdentityHashMap<>();

    @BeforeMapping
    public <T> T getExistingMappedInstance(Object source, @TargetType Class<T> targetType) {
        return (T) mappedInstances.get(source);
    }

    @BeforeMapping
    public void storeMappedInstance(Object source, @MappingTarget Object target) {
        mappedInstances.put(source, target);
    }
}

// 在所有层级的映射器中使用该上下文
@Mapper(componentModel = "spring")
public interface ProjectMapper {
    ProjectDTO toDto(Project project, @Context CycleAvoidingMappingContext context);

    DocumentClassDTO toDto(DocumentClass documentClass, @Context CycleAvoidingMappingContext context);

    DocumentTypeDTO toDto(DocumentType documentType, @Context CycleAvoidingMappingContext context);

    DocumentDTO toDto(Document document, @Context CycleAvoidingMappingContext context);
}

调用映射方法时，只需传入一个新的CycleAvoidingMappingContext实例：

ProjectDTO dto = projectMapper.toDto(project, new CycleAvoidingMappingContext());

这种方式适用于复杂的多循环依赖场景，MapStruct会自动利用上下文对象跳过已映射的实例，避免无限递归。

3. 修正@Mapping忽略路径的配置（针对MapStruct 1.5.1） #

你之前尝试的@Mapping(target="documentClasses.documentTypes.documents.documentType", ignore=true)无效，是因为MapStruct 1.5.1对深层嵌套路径的ignore支持有限，需要在直接关联的映射器中配置忽略，而不是在顶层ProjectMapper中：

示例代码： #

@Mapper(componentModel = "spring")
public interface DocumentMapper {
    @Mapping(target = "documentType", ignore = true)
    DocumentDTO toDto(Document document);
}

// 在DocumentTypeMapper中使用该DocumentMapper
@Mapper(componentModel = "spring", uses = {DocumentMapper.class})
public interface DocumentTypeMapper {
    DocumentTypeDTO toDto(DocumentType documentType);
}

这种方式把忽略配置放在最底层的DocumentMapper中，直接切断DocumentDTO对DocumentType的引用，从根源解决循环。

额外注意事项 #

• 确保你的DTO结构没有不必要的双向引用：比如DocumentDTO中如果不需要DocumentTypeDTO的完整信息，只保留documentTypeId即可，既减少数据传输量，也从结构上避免循环。
• 实体类的@EqualsAndHashCode(exclude = "documentType")主要影响equals/hashCode方法，和映射时的StackOverflowError关联不大，错误根源是映射递归调用，而非equals方法循环。

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