如何使用MapStruct实现嵌套集合中DocId到Doc的属性映射？

阿华AIGC实验室

2026-5-14

解决MapStruct嵌套集合映射的问题

你的问题出在直接对集合类型的属性写映射路径——MapStruct没办法直接识别这种针对集合整体的嵌套属性映射逻辑。要处理这种嵌套Bean的集合转换，你得先定义单个Xyz到XyzDTO的映射规则，MapStruct会自动把这个规则应用到集合里的每一个元素上。

下面是具体的实现步骤：

1. 先明确DocDTO的映射基础

假设你的DocDTO类有接收docId的构造方法，或者有对应的Setter方法，比如：

class DocDTO {
    private String id;
    
    // 用docId构造实例
    public DocDTO(String id) {
        this.id = id;
    }
    
    // Getter & Setter
}

2. 定义单个Xyz到XyzDTO的映射方法

在你的Mapper接口里，先单独写好单个对象的转换逻辑，专门处理docId到document的映射：

@Mapper
public interface AbcMapper {
    // 处理单个Xyz到XyzDTO的转换，重点映射docId到document
    @Mapping(source = "docId", target = "document", qualifiedByName = "docIdToDocDTO")
    XyzDTO xyzToXyzDTO(Xyz xyz);

    // 自定义转换逻辑：把字符串docId转成DocDTO实例
    @Named("docIdToDocDTO")
    default DocDTO docIdToDocDTO(String docId) {
        return new DocDTO(docId);
    }

    // 自动完成Abc到AbcDTO的映射，包括List<Xyz>到List<XyzDTO>的批量转换
    AbcDTO abcToAbcDTO(Abc abc);
}

如果你的DocDTO是通过Setter方法赋值（比如有setId(String id)），也可以直接用路径映射省略自定义方法：

@Mapping(source = "docId", target = "document.id")
XyzDTO xyzToXyzDTO(Xyz xyz);

3. 为什么你的原写法不生效？

你之前尝试的@Mapping(source = "xyz.docId", target = "xyz.doc")无法工作，核心原因是xyz是List<Xyz>集合类型，MapStruct不能直接对集合整体解析属性路径。只有当你定义了单个元素的映射规则后，它才会自动遍历集合里的每一项，套用规则完成整个集合的转换。