在 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 的语义本源，即可高效、清晰地完成复杂映射场景。
