引言：集合映射中的额外参数需求
在软件开发中，我们经常需要使用mapstruct等映射工具将一个数据传输对象（dto）或领域模型（domain model）转换为另一个。当处理单个对象时，直接在映射方法中添加额外参数并进行映射是直观的。然而，当涉及到集合（如list<myom>到list<myentity>)的映射时，如果每个映射后的myentity都需要一个从外部传入的公共参数（例如一个批次id或父级id），如何有效地将这个参数从集合映射方法传递到每个单独的元素映射方法，就成了一个需要解决的问题。
MapStruct提供了一个优雅的解决方案，即使用@Context注解结合一个代理方法，来实现在集合映射过程中向下传递额外参数。
核心概念：@Context注解
@Context注解是MapStruct在1.2版本引入的一个特性，它允许你将一个参数标记为“上下文”参数。这意味着该参数不会被MapStruct视为源对象的一部分进行常规映射，而是作为一个辅助值，可以向下传递给其他被调用的映射方法。
当你在一个集合映射方法中将某个参数标记为@Context时，MapStruct会尝试将这个上下文参数传递给其内部为每个元素调用的单个对象映射方法。
实践：在集合映射中传递额外参数
假设我们有MyOM和MyEntity两个类，它们都包含一个id字段。我们的目标是，在将List<MyOM>映射到List<MyEntity>时，为每个MyEntity设置一个外部传入的id。
1. 定义单个对象映射方法
首先，我们需要一个能够处理单个MyOM到MyEntity映射的方法，并且这个方法能够接收我们想要传递的额外id参数。
// 假设 MyOM 和 MyEntity 类已定义，并包含适当的字段和getter/setter
public class MyOM {
private String name;
// ... 其他字段
// getters/setters
}
public class MyEntity {
private String id; // 这个id将由外部参数提供
private String name;
// ... 其他字段
// getters/setters
}
@Mapper
public interface MyMapper {
/**
* 将单个 MyOM 映射到 MyEntity，并使用传入的 id 参数设置 MyEntity 的 id 字段。
*/
@Mapping(target = "id", expression = "java(id)")
MyEntity map(MyOM om, String id);
// ... 其他映射方法
}在这个方法中，@Mapping(target = "id", expression = "java(id)")明确指示MapStruct使用传入的id参数来设置MyEntity的id字段。
2. 定义集合对象映射方法并使用@Context
接下来，我们定义集合映射方法。关键在于将需要向下传递的参数标记为@Context。
@Mapper
public interface MyMapper {
// ... 上面的单个对象映射方法
/**
* 将 MyOM 列表映射到 MyEntity 列表。
* @param dtos 源 MyOM 列表。
* @param id 额外需要传递的上下文 ID，使用 @Context 注解标记。
* 注意：此处不需要为 id 添加 @Mapping 注解，因为它是上下文参数，
* 其作用是向下传递给内部调用的单个映射方法。
*/
List<MyEntity> mapDTOs(List<MyOM> dtos, @Context String id);
// ... 代理方法将在下一步添加
}请注意，在mapDTOs方法中，我们没有为id参数添加@Mapping注解。这是因为@Context参数的主要目的是传播，而不是直接作为源字段进行映射。
3. 添加默认的代理方法（关键步骤）
仅仅使用@Context注解不足以让MapStruct知道如何将这个上下文参数传递给正确的单个对象映射方法。默认情况下，MapStruct在处理集合时，如果它找到一个不带@Context参数的单个映射方法，它可能会选择那个方法，从而导致上下文参数丢失。
为了解决这个问题，我们需要添加一个default代理方法。这个代理方法会明确地调用我们之前定义的单个对象映射方法，并确保@Context参数被正确传递。
@Mapper
public interface MyMapper {
/**
* 将单个 MyOM 映射到 MyEntity，并使用传入的 id 参数设置 MyEntity 的 id 字段。
*/
@Mapping(target = "id", expression = "java(id)")
MyEntity map(MyOM om, String id);
/**
* 将 MyOM 列表映射到 MyEntity 列表。
* @param dtos 源 MyOM 列表。
* @param id 额外需要传递的上下文 ID，使用 @Context 注解标记。
*/
List<MyEntity> mapDTOs(List<MyOM> dtos, @Context String id);
/**
* 代理方法：确保 @Context 参数被正确传递给单个对象映射方法。
* 当 MapStruct 处理 List<MyOM> 并需要映射每个 MyOM 时，
* 它会优先寻找与 mapDTOs 方法签名匹配（包括 @Context 参数）的单个映射方法。
* 此 default 方法提供了这个匹配，并显式调用了带有 id 参数的 map(MyOM, String) 方法。
*/
default MyEntity mapContext(MyOM om, @Context String id) {
return map(om, id);
}
}通过添加mapContext这个default方法，我们明确地告诉MapStruct：当你在mapDTOs内部循环映射每个MyOM时，并且存在一个@Context String id参数时，请使用mapContext这个方法来处理，而mapContext又会调用我们预期的map(MyOM om, String id)方法，从而将id参数成功传递下去。
注意事项与最佳实践
- MapStruct版本要求：@Context注解是在MapStruct 1.2版本中引入的。请确保你的项目使用的MapStruct版本不低于此。
- @Context参数的性质：@Context参数不应被视为源对象的一部分。它是一个辅助性的、上下文相关的参数，其主要作用是传递和影响映射过程中的某些逻辑，而不是直接映射到目标对象的字段。
- 代理方法的命名：代理方法的命名（如mapContext）是任意的，但建议保持清晰和描述性。重要的是其方法签名（包括@Context参数）能够与集合映射方法内部对单个元素映射的需求相匹配。
- 避免歧义：如果存在多个签名的单个对象映射方法，并且它们之间可能引起歧义，那么代理方法的作用就更加关键，它能明确指定应该使用哪个映射逻辑。
总结
通过巧妙地结合@Context注解和default代理方法，MapStruct提供了一个强大且灵活的机制，用于在集合映射过程中向下传递额外的上下文参数。这不仅简化了代码，提高了可读性，也使得映射逻辑更加健壮和可维护。理解并掌握这一模式，能够帮助开发者更好地利用MapStruct的强大功能，应对复杂的映射场景。
