Spring Boot中MapStruct的用法

下面通过一个具体的业务场景演示 MapStruct 在 Spring Boot 项目中的完整用法。我们将实现AuditInfoBO业务对象到AuditInfoDTO数据传输对象的转换包括字段映射、嵌套对象、集合处理等常见情况。场景说明假设我们有一个审计日志模块BO 包含了审计记录的基本信息、操作人信息和操作项列表DTO 需要将这些数据返回给前端同时做一些字段调整如字段重命名、状态码转描述。1. 定义 BO 和 DTO 类BO 类业务对象java// AuditInfoBO.java import java.time.LocalDateTime; import java.util.List; public class AuditInfoBO { private Long id; private String action; // 操作动作 private Integer status; // 状态码0-成功1-失败 private LocalDateTime createTime; // 创建时间 private UserBO operator; // 操作人嵌套 private ListAuditItemBO items; // 操作项列表 // 构造器、getter/setter 省略可用 Lombok }java// UserBO.java public class UserBO { private Long userId; private String userName; private String email; // getter/setter }java// AuditItemBO.java public class AuditItemBO { private String itemId; private String itemName; private Integer quantity; // getter/setter }DTO 类数据传输对象java// AuditInfoDTO.java import java.time.LocalDate; import java.util.List; public class AuditInfoDTO { private Long id; private String action; private String statusDesc; // 状态描述由 status 转换而来 private LocalDate createDate; // 仅日期原 createTime 是 LocalDateTime private UserDTO operator; // 操作人嵌套 private ListAuditItemDTO items; // 操作项列表 // getter/setter }java// UserDTO.java public class UserDTO { private Long id; // 字段名与 BO 不同原 userId - id private String name; // 字段名不同原 userName - name private String email; // getter/setter }java// AuditItemDTO.java public class AuditItemDTO { private String itemId; private String itemName; private Integer quantity; // getter/setter }2. 创建 MapStruct Mapper 接口我们将使用Mapper注解并通过componentModel spring将其注册为 Spring Bean。java// AuditInfoMapper.java import org.mapstruct.Mapper; import org.mapstruct.Mapping; import org.mapstruct.Named; Mapper(componentModel spring) // 生成 Spring Bean public interface AuditInfoMapper { // 基础映射同名属性会自动映射如 id - id, action - action Mapping(source createTime, target createDate, dateFormat yyyy-MM-dd) Mapping(source status, target statusDesc, qualifiedByName statusToDesc) Mapping(source operator, target operator) Mapping(source items, target items) AuditInfoDTO toDto(AuditInfoBO bo); // 处理嵌套对象 UserBO - UserDTO单独定义映射方法MapStruct 会自动调用 Mapping(source userId, target id) Mapping(source userName, target name) UserDTO toUserDto(UserBO userBO); // 处理嵌套集合中的每个元素自动调用下面的方法 AuditItemDTO toItemDto(AuditItemBO itemBO); // 自定义方法将状态码转换为描述 Named(statusToDesc) default String statusToDesc(Integer status) { if (status null) return 未知; switch (status) { case 0: return 成功; case 1: return 失败; default: return 其他; } } }说明Mapping(source createTime, target createDate, dateFormat yyyy-MM-dd)将LocalDateTime格式化为指定格式的字符串如果目标类型是String但这里目标是LocalDateMapStruct 会自动截取日期部分dateFormat用于明确转换格式。Mapping(source status, target statusDesc, qualifiedByName statusToDesc)通过自定义方法statusToDesc将状态码转换为描述。嵌套对象operator和集合items的映射MapStruct 会自动查找类型匹配的映射方法toUserDto和toItemDto无需额外注解。如果字段名完全一致连Mapping都不需要直接自动映射。3. 在 Service 中使用 Mapperjava// AuditService.java import org.springframework.beans.factory.annotation.Autowired; import org.springframework.stereotype.Service; import java.util.List; Service public class AuditService { Autowired private AuditMapper mybatisMapper; // MyBatis 的 Mapper数据库操作 Autowired private AuditInfoMapper mapstructMapper; // MapStruct 的 Mapper对象转换 public AuditInfoDTO getAuditInfo(Long id) { // 1. 从数据库查询 BO由 MyBatis 直接映射为 BO 或 Entity AuditInfoBO bo mybatisMapper.selectAuditInfoBO(id); // 2. 使用 MapStruct 转换为 DTO AuditInfoDTO dto mapstructMapper.toDto(bo); return dto; } public ListAuditInfoDTO getAuditList() { ListAuditInfoBO boList mybatisMapper.selectAll(); // 3. 集合映射MapStruct 会逐个转换 return mapstructMapper.toDtoList(boList); // 需要额外定义 toDtoList 方法 } }为了让集合映射更简洁可以在 Mapper 接口中增加默认方法或直接定义javaMapper(componentModel spring) public interface AuditInfoMapper { // ... 已有的映射方法 ListAuditInfoDTO toDtoList(ListAuditInfoBO boList); }MapStruct 会自动生成实现遍历集合并调用toDto方法。4. 编译后生成的实现类供理解执行mvn clean compile后MapStruct 会在target/generated-sources/annotations下生成一个实现类大致内容如下javaComponent public class AuditInfoMapperImpl implements AuditInfoMapper { Override public AuditInfoDTO toDto(AuditInfoBO bo) { if (bo null) return null; AuditInfoDTO dto new AuditInfoDTO(); dto.setId(bo.getId()); dto.setAction(bo.getAction()); // 处理自定义映射 dto.setCreateDate(bo.getCreateTime().toLocalDate()); // 根据 dateFormat 处理 dto.setStatusDesc(statusToDesc(bo.getStatus())); dto.setOperator(toUserDto(bo.getOperator())); dto.setItems(toItemDtoList(bo.getItems())); return dto; } Override public UserDTO toUserDto(UserBO userBO) { if (userBO null) return null; UserDTO dto new UserDTO(); dto.setId(userBO.getUserId()); dto.setName(userBO.getUserName()); dto.setEmail(userBO.getEmail()); return dto; } Override public AuditItemDTO toItemDto(AuditItemBO itemBO) { // 同名属性直接映射 // ... } Override public ListAuditInfoDTO toDtoList(ListAuditInfoBO boList) { // 循环调用 toDto } }5. 与 BeanUtils.copyProperties 对比特性MapStructBeanUtils.copyProperties类型安全编译期检查字段类型、名称运行时可能抛出异常性能直接调用 getter/setter无反射反射调用性能较低嵌套对象映射自动递归映射需定义嵌套映射方法浅拷贝只复制引用集合映射自动生成循环代码需手动遍历自定义转换表达式、默认方法、自定义类型转换器无法直接实现需转换前/后处理字段名称不一致Mapping明确指定无法自动处理必须手动 set代码可读性映射规则集中在一个接口清晰分散在业务代码中难以追踪6. 注意事项与 MyBatis Mapper 同名问题将 MapStruct 的 Mapper 放在不同包如converter命名用XxxConverter或XxxStructMapper避免混淆。Lombok 配合如果 BO/DTO 使用了 Lombok确保pom.xml中正确配置了lombok-mapstruct-binding否则可能出现属性找不到的错误。复杂映射若需更复杂的类型转换如String转Enum可定义自定义类型转换器Mapper的uses属性。总结通过这个例子可以看出MapStruct 将对象转换逻辑从业务代码中抽离以声明式接口定义映射规则既清晰又高效。在 Spring Boot 项目中搭配componentModel spring可以无缝集成是替代BeanUtils.copyProperties的理想选择。