17370845950

在 mapstruct 中，当映射方法接收多个参数（如实体 + 额外字符串）时，需通过 `@mapping(source = "paramname")` 显式指定源参数名，而非 `qualifiedbyname`——后者仅用于调用带 `@named` 注解的自定义映射方法。

MapStruct 支持多源参数映射，但关键在于理解 source 与 qualifiedByName 的语义差异：

• ✅ source = "shortText"：明确将方法签名中名为 shortText 的参数值赋给目标字段（如 content.shortText）；
• ❌ qualifiedByName = "shortText"：试图查找一个名为 "shortText" 的、带 @Named("shortText") 注解的独立映射方法，与参数名无关，因此无法实现预期的直连赋值。

正确写法如下：

@Mapper
public interface EntityMapper {
    @Mapping(target = "content.shortText", source = "shortText")
    @Mapping(target = "content.longText", source = "longText")
    EntityDto mapToDto(Entity entity, String shortText, String longText);
}

调用时：

EntityDto dto = mapper.mapToDto(entity, "Hello", "WorldLong");
// 结果：dto.getContent().getShortText() == "Hello"
//       dto.getContent().getLongText()  == "WorldLong"

⚠️ 注意事项：

• source 值必须严格匹配方法参数名（区分大小写），不可为表达式或路径（如 entity.name 不合法，因 entity 是独立参数，其属性需通过 expression 或嵌套映射处理）；
• 若需对参数做转换（如截断、格式化），可结合 expression：

  @Mapping(target = "content.shortText", 
            expression = "java(shortText != null ? shortText.substring(0, Math.min(50, shortText.length())) : null)")

• 多参数映射不支持 @BeanMapping(ignoreByDefault = true) 的隐式忽略，所有字段映射必须显式声明。

总结：MapStruct 的多参数映射本质是“命名绑定”，核心是 source 属性——它让框架精准识别哪个入参流向哪个目标路径。抛弃对 qualifiedByName 的误用，回归 source 的语义本源，即可高效、清晰地完成复杂映射场景。