在 mapstruct 中，当使用多参数映射方法时，需通过 `source` 属性显式指定参数名，而非 `qualifiedbyname`（后者仅用于调用自定义命名转换方法），才能将额外参数准确映射至嵌套目标字段（如 `content.shorttext`）。
MapStruct 支持将多个方法参数作为映射源，但必须通过 @Mapping(source = "...") 明确声明每个参数与目标属性的对应关系。qualifiedByName 仅适用于委托给带有 @Named 注解的自定义映射方法（例如类型转换逻辑），不能用于直接引用方法参数。若错误地将其用于参数绑定（如 qualifiedByName = "shortText"），MapStruct 将无法识别该“名称”为有效源，导致编译失败或静默忽略映射。
✅ 正确做法是：在 @Mapping 中使用 source 属性，其值必须严格匹配方法签名中对应参数的形参名（Java 8+ 需启用 -parameters 编译选项以保留参数名；否则需配合 @Param 注解）：
@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 值区分大小写，且必须与方法参数名完全一致；
- 若未启用 -parameters 编译参数（Maven 中可配置
-parameters EntityDto mapToDto(Entity entity, @Param("shortText") String shortText, @Param("longText") String longText); - 目标路径（如 "content.shortText"）支持点号分隔的嵌套属性，MapStruct 会自动处理中间对象（content）的实例化（前提是其有无参构造函数或已配置 @BeanMapping(nullValuePropertyMappingStrategy = SET_TO_NULL) 等策略）；
- 不要混淆 source（指定源参数/属性）与 qualifiedByName（指定转换方法名）——前者解决“从哪取值”，后者解决“如何转换”。
掌握这一机制后，即可灵活组合实体对象与上下文参数（如当前用户、时间戳、配置值等）完成复杂 DTO 构建，大幅提升映射表达力与代码可维护性。
