MapStruct 多参数映射：如何正确将方法参数作为源字段映射到嵌套目标属性

在 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 等语义。