使用MapStruct映射关联DTO列表时避免栈溢出的最佳实践是什么？

问题根因 #

你遇到的栈溢出是双向关联DTO的递归映射导致的：TaskDTO持有UserDTO实例，UserDTO持有List<TaskDTO>集合，MapStruct默认的映射逻辑会循环调用两个Mapper的转换方法，无限递归最终触发栈溢出。

业内通用解决方案 #

1. 拆分场景专用的细粒度DTO #

这是最符合DTO设计原则的方案，DTO本身就是为不同业务场景按需传递数据设计的，不需要做全量字段的大而全DTO：

• 任务查询场景使用TaskDetailDTO，关联的用户属性使用只包含基础字段、不带任务集合的UserSimpleDTO
• 用户查询场景使用UserDetailDTO，关联的任务属性使用只包含基础字段、不带用户属性的TaskSimpleDTO
  从结构上直接切断循环关联的可能，也避免了无效字段的传输，后续业务迭代的可维护性最高，你自己想到的方案就属于这一类。

2. MapStruct 配置忽略循环关联字段 #

不需要新增DTO类，直接在Mapper接口上通过注解配置忽略反向引用的字段即可，改造成本最低：
比如需要在UserDTO中保留任务集合，只需要在UserMapper的转换方法上配置忽略任务下的用户属性：

@Mapper(componentModel = "spring")
public interface UserMapper {
    // 映射User到UserDTO时，忽略tasks集合下每个task的user属性，切断递归
    @Mapping(target = "tasks.user", ignore = true)
    UserDTO toDTO(User user);
}

如果需要在TaskDTO中保留用户属性，同理给TaskMapper的转换方法加上@Mapping(target = "user.tasks", ignore = true)即可。

3. 序列化层注解处理循环引用 #

如果你的DTO会直接作为接口返回值序列化，还可以搭配JSON序列化框架的注解解决循环序列化的问题：

• 使用Jackson的@JsonManagedReference和@JsonBackReference：在TaskDTO的user字段上加@JsonManagedReference，在UserDTO的tasks字段上加@JsonBackReference，序列化时会自动忽略反向引用
• 或者给两个DTO类都加上@JsonIdentityInfo(generator = ObjectIdGenerators.PropertyGenerator.class, property = "id")，序列化时遇到已经输出过的对象，只会输出ID不会递归展开
  注意这个方案仅解决JSON序列化的循环问题，如果是实体转DTO阶段就已经栈溢出，还是需要配合MapStruct的忽略配置使用。

4. 映射上下文缓存已转换对象 #

针对多对象交叉引用的复杂场景，可以使用MapStruct的@Context上下文缓存已经转换过的对象，遇到相同实例直接返回缓存结果，避免重复转换：
首先实现循环规避的上下文类：

public class CycleAvoidingMappingContext {
    private Map<Object, Object> knownInstances = new IdentityHashMap<>();

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

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

然后在Mapper方法中传入上下文参数即可：

@Mapper(componentModel = "spring")
public interface TaskMapper {
    TaskDTO toDTO(Task task, @Context CycleAvoidingMappingContext context);
}

调用转换方法时传入新的上下文实例即可自动处理循环引用。

内容的提问来源于stack exchange，提问作者Олександр Житарюк