在 mapstruct 中，当映射方法接收多个参数时，需通过 `@mapping(source = "paramname")` 显式指定非实体参数作为源值，而非使用 `qualifiedbyname`（该注解仅用于调用自定义命名转换方法）。
MapStruct 支持多源参数映射，但关键在于区分「源字段引用」与「自定义转换逻辑」。qualifiedByName 的作用是匹配带有 @Named("xxx") 注解的转换方法（如字符串截断、格式化等），它不用于选取方法参数作为映射源。若你想将第二个或第三个参数（如 String shortText）直接赋值给目标对象的嵌套属性（如 content.shortText），必须使用 source 属性，并确保参数名与 source 值严格一致（支持点号路径，但此处为顶层参数，无需前缀）。
✅ 正确写法如下：
@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(myEntity, "Hello", "WorldLong"); // 结果：dto.getContent().getShortText() == "Hello" // dto.getContent().getLongText() == "WorldLong"
⚠️ 注意事项：
- source 值必须与方法参数名完全相同（区分大小写），MapStruct 会自动识别并绑定；
- 若参数是对象类型（如 User user），可使用点号访问其属性：source = "user.name"；
- qualifiedByName 仅适用于需要额外处理的场景，例如：
@Named("shortText") public static String toShortText(String text) { return text != null ? text.substring(0, Math.min(50, text.length())) : null; } // 此时才配合 @Mapping(..., qualifiedByName = "shortText") - 确保目标属性 content 已被正确初始化（可通过 @BeanMapping(nullValuePropertyMappingStrategy = SET_TO_NULL) 或构造器/工厂方法控制）。
总结：多参数映射的核心是明确 source —— 它指向方法签名中的参数名；而 qualifiedByName 是转换策略的“路由开关”，二者职责不同，不可混用。
