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

心靈之曲 2026-01-12 00:00:00 次阅读

在 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"

⚠️ 注意事项：

❌ 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 值。