MapStruct内部字段映射null问题：Chat关联Message映射失败

我在应用中设计了Chat包含一组Message，每条Message包含发送方和接收方的用户ID（userFromId/userToId）。用ChatMapper直接把ChatEntity映射为Chat时，Message的基础内容正常，但userFromId和userToId始终为null；但手动用MessageMapper逐个映射Message再组装Chat就能正常获取用户ID。我试过在ChatMapper上添加@Mapper(uses = MessageMapper.class)，问题依然存在，想知道原因。

相关代码 #

失败的映射代码 #

return chatRepository.findAll()
        .stream()
        .map(chatMapper::toModel)
        .toList();

成功的手动映射代码 #

List<ChatEntity> chatEntityList = chatRepository.findAll();
List<Chat> chatList = new ArrayList<>();
for (ChatEntity chatEntity : chatEntityList) {
    List<Message> messageList = chatEntity.getMessageEntityList()
            .stream()
            .map(messageMapper::toModel)
            .toList();
    Chat chat = Chat.builder()
            .id(chatEntity.getId())
            .messageList(messageList)
            .build();
    chatList.add(chat);
}
return chatList;

Mapper定义 #

ChatMapper

@Mapper // 尝试过@Mapper(uses = MessageMapper.class)，结果一致
public interface ChatMapper {
    @Mapping(source = "messageList", target = "messageEntityList")
    ChatEntity toEntity(Chat chat);
    @Mapping(source = "messageEntityList", target = "messageList")
    Chat toModel(ChatEntity chatEntity);
}

MessageMapper

@Mapper
public interface MessageMapper {
    @Mapping(source = "userFromId", target = "userFromEntity.id")
    @Mapping(source = "userToId", target = "userToEntity.id")
    MessageEntity toEntity(Message message);
    @Mapping(source = "userFromEntity.id", target = "userFromId")
    @Mapping(source = "userToEntity.id", target = "userToId")
    Message toModel(MessageEntity messageEntity);
}

问题原因 #

MapStruct处理集合映射时，若未明确指定使用自定义Mapper，会自动生成默认的集合映射逻辑——仅复制同名字段，不会处理userFromEntity.id到userFromId这类嵌套字段的映射规则。即便在ChatMapper上添加@Mapper(uses = MessageMapper.class)，MapStruct也可能未正确识别需要委托MessageMapper处理单个MessageEntity到Message的转换，仍用默认逻辑生成集合映射代码，导致用户ID字段为null。

解决方案 #

1. 确保ChatMapper正确依赖MessageMapper #

修改ChatMapper的注解，明确指定依赖MessageMapper，同时保证项目能扫描到MessageMapper的实现类：

@Mapper(uses = MessageMapper.class)
public interface ChatMapper {
    @Mapping(source = "messageList", target = "messageEntityList")
    ChatEntity toEntity(Chat chat);
    @Mapping(source = "messageEntityList", target = "messageList")
    Chat toModel(ChatEntity chatEntity);
}

2. 显式声明单个元素的映射方法（兜底方案） #

若上述方法仍不生效，可在ChatMapper中显式定义MessageEntity到Message的映射方法，强制MapStruct调用MessageMapper的转换逻辑：

@Mapper(uses = MessageMapper.class)
public interface ChatMapper {
    @Mapping(source = "messageList", target = "messageEntityList")
    ChatEntity toEntity(Chat chat);
    @Mapping(source = "messageEntityList", target = "messageList")
    Chat toModel(ChatEntity chatEntity);

    // 显式委托给MessageMapper的转换方法
    Message toMessage(MessageEntity messageEntity);
}

MapStruct生成实现时，会自动将toMessage方法指向MessageMapper.toModel()，从而正确处理集合中每个Message的嵌套字段映射。

3. 检查MapStruct版本与构建配置 #

确保使用最新稳定版MapStruct，同时验证Maven/Gradle的注解处理器配置正确，保证Mapper实现类能正常生成。

内容的提问来源于stack exchange，提问作者Francislainy Campos