在Java项目开发中，MapStruct是常用的对象映射工具，能够自动生成类型安全的转换代码。当转换方法需要接收多个参数，且部分参数需要映射到目标对象的嵌套属性时，很多开发者会遇到配置困惑，不知道如何正确指定源字段的来源。
多参数映射的基本配置规则
MapStruct的@Mapping注解的source属性支持通过参数名.属性名的格式指定源字段，当目标属性是嵌套对象时，只需要按照嵌套层级拼接对应的属性路径即可。如果是直接将方法参数作为源值，不需要额外拼接属性路径，直接使用参数名即可。
基础场景示例
假设我们有两个源对象和一个目标对象，目标对象包含嵌套的用户信息属性，需要将两个源对象的字段和方法的直接参数映射到目标对象中。
首先定义源对象：
// 用户基础信息源对象
public class UserSource {
private Long id;
private String name;
// 省略getter、setter
}
// 用户扩展信息源对象
public class UserExtSource {
private Integer age;
private String address;
// 省略getter、setter
}
目标对象定义，包含嵌套的用户基础信息属性：
// 嵌套的用户基础信息属性类
public class UserBaseTarget {
private Long userId;
private String userName;
// 省略getter、setter
}
// 最终目标对象
public class UserTarget {
private UserBaseTarget userBase;
private Integer userAge;
private String userAddress;
private String operateTime;
// 省略getter、setter
}
多参数映射器实现
转换方法接收两个源对象和一个直接参数，将参数映射到目标对象的嵌套属性userBase中：
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
@Mapper(componentModel = "spring")
public interface UserMapper {
@Mapping(source = "userSource.id", target = "userBase.userId")
@Mapping(source = "userSource.name", target = "userBase.userName")
@Mapping(source = "userExtSource.age", target = "userAge")
@Mapping(source = "userExtSource.address", target = "userAddress")
@Mapping(source = "operateTimeParam", target = "operateTime")
UserTarget convert(UserSource userSource, UserExtSource userExtSource, String operateTimeParam);
}
上述配置中，userBase.userId是嵌套目标属性，对应的源是userSource.id，也就是第一个参数的id属性；operateTimeParam是方法的直接参数，直接作为源映射到operateTime属性，不需要拼接额外路径。
常见错误与排查
- 参数名不匹配：
@Mapping的source中使用的参数名必须和转换方法的参数名完全一致，否则会编译报错。 - 嵌套路径错误：目标嵌套属性的路径需要和实际的目标对象结构一致，比如
userBase.userName必须对应目标对象中userBase属性的userName字段。 - 类型不匹配：源字段和目标字段的类型需要兼容，否则MapStruct会尝试生成类型转换代码，如果无法转换会报错。
自定义转换规则补充
如果源字段和目标字段的类型无法直接映射，可以通过@Mapping的qualifiedByName属性指定自定义的转换方法：
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.Named;
@Mapper(componentModel = "spring")
public interface UserMapper {
@Mapping(source = "userSource.id", target = "userBase.userId", qualifiedByName = "idToString")
@Mapping(source = "userSource.name", target = "userBase.userName")
@Mapping(source = "userExtSource.age", target = "userAge")
@Mapping(source = "userExtSource.address", target = "userAddress")
@Mapping(source = "operateTimeParam", target = "operateTime")
UserTarget convert(UserSource userSource, UserExtSource userExtSource, String operateTimeParam);
@Named("idToString")
static String idToString(Long id) {
return id == null ? null : String.valueOf(id);
}
}
上述示例中，将Long类型的id转换为String类型再映射到嵌套的userId属性，解决了类型不匹配的问题。