本文详解 mapstruct 中 @context 的作用机制，澄清“上下文参数必须显式声明在映射方法签名中”这一关键规则，并通过对比 context 传参与自动装配两种方案，提供可直接落地的代码示例与最佳实践。
本文详解 mapstruct 中 @context 的作用机制，澄清“上下文参数必须显式声明在映射方法签名中”这一关键规则，并通过对比 context 传参与自动装配两种方案，提供可直接落地的代码示例与最佳实践。
在 MapStruct 中，@Context 注解用于向映射逻辑（如 @Named 方法）传递运行时依赖（如 DAO、Service 或配置对象），但它不会被自动注入或隐式推导——这是开发者最常见的误区。你遇到的 Qualifier error 正源于此：当 @Mapping(qualifiedByName = "getEnumDefinition") 引用一个带 @Context 参数的方法时，MapStruct 要求该方法的调用上下文必须由映射方法自身显式提供，即：源对象参数之后、目标类型之前，需明确定义 @Context 类型的参数。
✅ 正确做法是：将 @Context 参数添加到 mapper 接口的映射方法签名中，并确保 @Named 方法也声明对应的 @Context 参数（且类型一致）。如下所示：
@Mapper
public interface EnumValueMapperWithContext {
// ✅ 显式声明 @Context 参数 —— 这是关键！
@Mapping(target = "enumDefinition", source = "enumDefinitionId", qualifiedByName = "getEnumDefinition")
EnumValue toEntity(EnumValueBean enumValueBean, @Context IEnumDefinitionDao enumDefinitionDao);
@Mapping(target = "enumDefinitionId", source = "enumDefinition.name")
EnumValueBean toBean(EnumValue enumValue);
@Named("getEnumDefinition")
default EnumDefinition getEnumDefinition(
String enumDefinitionName,
@Context IEnumDefinitionDao enumDefinitionDao // ✅ 类型匹配，且标注 @Context
) {
return enumDefinitionDao.findById(enumDefinitionName).orElse(null);
}
}调用时，需手动传入上下文实例：
@Service
public class DefinitionService {
private final IEnumDefinitionDao enumDefinitionDao;
private final EnumValueMapperWithContext mapper;
public EnumValue mapWithManualContext(EnumValueBean bean) {
return mapper.toEntity(bean, enumDefinitionDao); // ✅ 手动传入 context
}
}⚠️ 注意事项：
- @Context 参数不能出现在 @Mapping#source 中，它仅用于辅助逻辑，不参与字段级映射；
- @Named 方法若含 @Context，其所在 mapper 方法签名必须包含同类型 @Context 参数，否则编译器无法解析重载匹配；
- @Context 参数在方法签名中位置灵活（通常置于末尾），但必须存在且类型精确匹配（接口/实现类不可混用）；
- 若希望避免每次调用都手动传参，可改用 抽象类 + @Autowired setter 注入 方案（如答案中 EnumValueMapperWithAutowiredBean），此时 @Context 不再需要，@Named 方法直接访问成员变量即可。
总结：@Context 不是“魔法注入”，而是 MapStruct 提供的一种显式上下文透传机制。理解其“契约性”——即 调用方声明 → 生成代码透传 → 辅助方法接收 的三段式协作流程，是规避 Qualifier error 和构建可维护映射逻辑的基础。推荐在 Spring 环境中优先采用抽象类 + 自动装配方式提升可读性；在需多上下文隔离（如多租户 DAO 切换）场景下，再选用接口 + @Context 显式传参模式。
