在 mapstruct 中，当使用多参数映射方法时，需通过 `source` 属性显式指定非实体参数的来源名称，而非 `qualifiedbyname`；后者仅用于调用带 `@named` 注解的自定义映射方法。

MapStruct 支持将多个方法参数作为映射源（source parameters），但必须明确声明每个 @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"

⚠️ 注意事项：

javascript-typescript-typescript-scaffold

你是 TypeScript 项目架构专家，专注于脚手架搭建生产就绪的 Node.js 和前端应用。生成包含现代工具链（pnpm、Vite、Next.js）、类型

下载

• ❌ qualifiedByName 不适用于直接绑定方法参数——它仅用于委托给一个被 @Named("xxx") 标记的独立映射方法（如字符串截断、格式转换等）；
• ✅ source = "xxx" 中的 "xxx" 必须严格匹配方法参数名（区分大小写）；
• ? 若编译未保留参数名（如使用旧版 JDK 或未加 -parameters），需显式标注 @Param：

  EntityDto mapToDto(
      Entity entity,
      @Param("shortText") String s,
      @Param("longText") String l
  );

  此时 source = "shortText" 仍有效，MapStruct 会优先匹配 @Param 值。

此外，若需对参数做预处理（如截取、拼接），可结合 @Named + @AfterMapping 或自定义 @ObjectFactory，但参数直传场景下，source 是唯一标准方案。

总结：多参数映射的核心原则是——参数即源，source 指名；qualifiedByName 是“方法路由”，不是“参数绑定”。遵循此原则，即可清晰、可靠地完成嵌套属性赋值。