MapStruct嵌套Bean映射问题：使用"."未实现属性全量映射排查

云上老周

2026-6-29

MapStruct 使用target="."未实现全量属性映射的问题排查与修复

错误原因

你的代码中，@Mapping(target = ".", qualifiedByName = "device")没有明确指定源对象，MapStruct无法识别要将哪个对象的属性映射到目标ClientRegisterDeviceRequest中。
无参的@Named("device")方法返回的DeviceInfo，和源参数RegisterDeviceRequest没有建立映射关联，MapStruct不知道要把这个DeviceInfo的属性平铺到目标对象上。

修复方案

方案一：通过`source`关联qualified方法的返回值

调整映射注解，指定source为源参数，同时让qualified方法接收该参数（即使方法内部不需要使用它，也能建立关联）：

@Mapping(target = ".", source = "registerDeviceRequest", qualifiedByName = "device")
public abstract ClientRegisterDeviceRequest toDeviceRequest(RegisterDeviceRequest registerDeviceRequest);

@Named("device")
public DeviceInfo device(RegisterDeviceRequest request) {
    // 可根据request做逻辑，或直接返回全局设备信息
    return DeviceInfoService.get();
}

方案二：使用`@Context`注入DeviceInfo

如果DeviceInfo是全局上下文对象，可通过@Context注入到映射方法，再明确source为该对象：

@Mapping(target = ".", source = "deviceInfo")
public abstract ClientRegisterDeviceRequest toDeviceRequest(RegisterDeviceRequest registerDeviceRequest,
                                                           @Context DeviceInfo deviceInfo);

// 如果需要通过服务获取，结合@Named：
@Mapping(target = ".", source = "deviceInfo")
public abstract ClientRegisterDeviceRequest toDeviceRequest(RegisterDeviceRequest registerDeviceRequest,
                                                           @Context @Named("device") DeviceInfo deviceInfo);

@Named("device")
public DeviceInfo getDevice() {
    return DeviceInfoService.get();
}