如何用MapStruct自动映射嵌套实体至DTO字段（替代手动映射）

问题背景 #

现有实体类：
BoardEntity：

public class BoardEntity {
    @Id
    private UUID boardId;
    private String content;
    private UserInfoEntity user;
}

UserInfoEntity：

public class UserInfoEntity {
    @Id
    private UUID userId;
    private String userName;
    private String userEmail;
    private String userPhone;
}

期望生成的ResponseDto：

public class ResponseDto {
    private UUID boardId;  // 来自BoardEntity
    private String content; // 来自BoardEntity
    private UUID userId;  // 来自BoardEntity.user.userId
    private String userName;  // 来自BoardEntity.user.userName
    // 其他字段...
}

需求是将BoardEntity的自身字段，以及其嵌套的UserInfoEntity中字段名匹配的字段，整合到ResponseDto中。当前通过逐个编写@Mapping实现，但字段较多时效率低下，希望找到自动映射的方法。

解决方案 #

MapStruct 提供了简洁的方式实现嵌套实体的自动映射，无需手动编写每个字段的映射规则：

方法1：指定嵌套对象作为源自动映射 #

通过@Mapping(source = "user", target = ".")告知MapStruct，将嵌套的user对象中所有字段，自动映射到DTO中同名的字段；同时BoardEntity自身的同名字段也会自动完成映射：

@Mapper
public interface BoardMapper {
    BoardMapper INSTANCE = Mappers.getMapper(BoardMapper.class);

    @Mapping(source = "user", target = ".")
    ResponseDto toDto(BoardEntity board);
}

方法2：配合忽略未映射字段（可选） #

如果DTO中存在无需映射的字段，或嵌套实体中有部分字段不需要同步到DTO，可以添加@BeanMapping配置忽略未映射字段，避免编译报错：

@Mapper
public interface BoardMapper {
    BoardMapper INSTANCE = Mappers.getMapper(BoardMapper.class);

    @Mapping(source = "user", target = ".")
    @BeanMapping(unmappedTargetPolicy = ReportingPolicy.IGNORE)
    ResponseDto toDto(BoardEntity board);
}

注意事项 #

• 该方式要求DTO中的字段名与嵌套实体中的字段名完全一致，比如DTO的userId必须对应UserInfoEntity的userId，否则需单独编写该字段的映射规则。
• 若嵌套实体与外部实体存在字段名冲突，MapStruct会优先使用外部实体的字段，此时需单独指定映射规则解决冲突。

内容的提问来源于stack exchange，提问作者남혁준