如何用MapStruct实现带非迭代UUID参数的对象到集合映射？

问题描述 #

定义了如下MapStruct映射方法，意图实现List到List的转换，但因存在非迭代参数UUID mapId导致无法正常工作：

List<MapStructureObjectEntity> toEntityTest(UUID mapId, MapStructureObjectDto.Update update);
List<MapStructureObjectEntity> toEntityTestList(UUID mapId, List<MapStructureObjectDto.Update> updateList);

需求是转换时将mapId赋值给所有生成的实体对象，目前通过Stream循环逐个调用映射方法实现：

updateList.stream().map(update -> MapStructureObjectMapper.MAPPER.toEntity(mapId, update)).toList();

但该方式不够优雅，存在重复操作且代码分散，希望找到MapStruct原生的便捷实现方式。

解决方案 #

MapStruct 原生支持批量转换时传递非迭代参数，无需手动编写Stream循环，以下是两种常用实现方式：

方式1：基于单个对象映射方法自动生成批量逻辑 #

首先定义单个对象的映射方法，明确mapId到实体字段的赋值规则：

@Mapping(target = "mapId", source = "mapId")
MapStructureObjectEntity toEntity(UUID mapId, MapStructureObjectDto.Update update);

接着直接声明批量转换方法，MapStruct会自动生成遍历列表、调用单个映射方法并传递mapId的实现：

List<MapStructureObjectEntity> toEntityList(UUID mapId, List<MapStructureObjectDto.Update> updateList);

生成的实现类会自动循环处理列表中的每个元素，将mapId赋值给对应的实体对象，代码简洁且集中在映射接口中。

方式2：使用@Context传递共享上下文参数 #

如果mapId需要在多步映射中共享，或场景更复杂，可使用@Context标记参数：

@Mapping(target = "mapId", source = "mapId")
MapStructureObjectEntity toEntity(MapStructureObjectDto.Update update, @Context UUID mapId);

List<MapStructureObjectEntity> toEntityList(List<MapStructureObjectDto.Update> updateList, @Context UUID mapId);

@Context标注的参数会被视为共享上下文，批量转换时会自动传递给每个单个对象的映射方法，无需额外处理遍历逻辑。

关键注意点 #

• 单个对象的映射方法需正确配置mapId的映射规则，字段名一致时可省略@Mapping注解；
• 无需手动实现批量方法的逻辑，MapStruct生成的代码比手写Stream更高效且易于维护。

内容的提问来源于stack exchange，提问作者남혁준