在 mapstruct 中，当使用多参数映射方法时，需通过 `@mapping(source = "paramname")` 显式指定非实体参数作为源，而非依赖 `qualifiedbyname`；否则无法将字符串等额外参数映射至嵌套目标路径（如 `content.shorttext`）。
MapStruct 支持将多个方法参数（如实体 + 普通值）联合映射到一个目标对象。关键在于：只有实体类字段可被自动解析为源，而额外传入的原始类型参数（如 String shortText）必须显式声明为 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(entity, "Hello", "WorldLong"); // → dto.getContent().getShortText() == "Hello" // → dto.getContent().getLongText() == "WorldLong"
⚠️ 常见误区说明：
- qualifiedByName 仅用于委托给另一个带 @Named 注解的自定义映射方法（例如格式化、转换逻辑），它不用于绑定方法参数；
- source = "shortText" 中的 "shortText" 必须严格匹配方法签名中参数的变量名（非类型名），且区分大小写；
- 若目标属性是嵌套路径（如 content.shortText），MapStruct 会自动处理中间对象（content）的实例化——前提是 EntityDto 的 content 字段有默认构造器或已初始化（否则需配合 @BeanMapping(nullValuePropertyMappingStrategy = SET_TO_NULL) 或自定义构建逻辑）。
? 补充建议：
- 如需对 shortText 或 longText 做预处理（如截断、脱敏），可结合 expression：
@Mapping(target = "content.shortText", expression = "java(shortText != null ? shortText.substring(0, Math.min(50, shortText.length())) : null)") - 对于复杂场景（如多个参数需组合生成单个字段），推荐使用 @AfterMapping 手动赋值，保持映射逻辑清晰可控。
掌握 source 参数绑定机制，是高效使用 MapStruct 多源映射的基础。务必以官方文档 Mappings with several source parameters 为准，避免混淆 source、qualifiedByName 和 constant 等语义。
