MapStruct完全指南：优雅解决Java Bean映射难题

<!-- MapStruct核心依赖 -->
<dependency>
    <groupId>org.mapstruct</groupId>
    <artifactId>mapstruct</artifactId>
    <version>1.5.5.Final</version> <!-- 稳定版，可按需升级 -->
</dependency>

<!-- 编译插件：生成映射实现类，必须配置 -->
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.8.1</version>
            <configuration>
                <source>8</source> <!-- 对应项目JDK版本 -->
                <target>8</target>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>1.5.5.Final</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

// 订单实体类（数据库映射）
@Data
public class Order {
    private Long id; // 订单ID
    private String orderNo; // 订单编号
    private Long userId; // 用户ID
    private BigDecimal amount; // 订单金额
    private Integer status; // 订单状态（0-待支付，1-已支付）
    private LocalDateTime createTime; // 创建时间
}

// 订单DTO（接口传输）
@Data
public class OrderDTO {
    private Long id; // 与实体类字段名一致
    private String orderNumber; // 与实体类orderNo字段名不一致
    private Long userId; // 与实体类字段名一致
    private String amount; // 与实体类类型不一致（实体类BigDecimal，DTO String）
    private String statusDesc; // 状态描述（实体类无对应字段，需自定义转换）
    private String createTime; // 与实体类类型不一致（实体类LocalDateTime，DTO String）
}

import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
import org.mapstruct.factory.Mappers;

// @Mapper：标识该接口为MapStruct映射接口，componentModel = "spring"表示生成Spring Bean
@Mapper(componentModel = "spring")
public interface OrderMapper {
    // 实例化映射器（非Spring环境使用，Spring环境可通过@Autowired注入）
    OrderMapper INSTANCE = Mappers.getMapper(OrderMapper.class);

    // 实体类转DTO：配置字段映射规则
    @Mapping(source = "orderNo", target = "orderNumber") // 字段名不一致：实体类orderNo -> DTO orderNumber
    @Mapping(source = "amount", target = "amount", dateFormat = "0.00") // 类型转换：BigDecimal -> String，保留两位小数
    @Mapping(source = "status", target = "statusDesc", expression = "java(convertStatus(order.getStatus()))") // 自定义表达式转换状态
    @Mapping(source = "createTime", target = "createTime", dateFormat = "yyyy-MM-dd HH:mm:ss") // 时间类型转换：LocalDateTime -> String
    OrderDTO orderToOrderDTO(Order order);

    // DTO转实体类：反向映射，字段规则可复用或单独配置
    @Mapping(source = "orderNumber", target = "orderNo")
    @Mapping(source = "amount", target = "amount") // String -> BigDecimal，MapStruct自动转换
    @Mapping(target = "status", ignore = true) // 忽略DTO的statusDesc字段，不映射到实体类
    @Mapping(source = "createTime", target = "createTime", dateFormat = "yyyy-MM-dd HH:mm:ss")
    Order orderDTOToOrder(OrderDTO orderDTO);

    // 自定义状态转换方法（映射接口内部可定义默认方法，供expression调用）
    default String convertStatus(Integer status) {
        if (status == null) {
            return "未知状态";
        }
        return status == 0 ? "待支付" : "已支付";
    }
}

@Service
public class OrderServiceImpl {
    // 注入MapStruct生成的映射器
    @Autowired
    private OrderMapper orderMapper;

    public void testMapping() {
        // 构建实体类对象
        Order order = new Order();
        order.setId(1L);
        order.setOrderNo("ORDER20260129001");
        order.setUserId(1003L);
        order.setAmount(new BigDecimal("399.50"));
        order.setStatus(0);
        order.setCreateTime(LocalDateTime.of(2026, 1, 29, 10, 30));

        // 实体类转DTO
        OrderDTO orderDTO = orderMapper.orderToOrderDTO(order);
        System.out.println(orderDTO);
        // 输出结果：OrderDTO(id=1, orderNumber=ORDER20260129001, userId=1003, amount=399.50, statusDesc=待支付, createTime=2026-01-29 10:30:00)

        // DTO转实体类
        Order convertOrder = orderMapper.orderDTOToOrder(orderDTO);
        System.out.println(convertOrder);
        // 输出结果：Order(id=1, orderNo=ORDER20260129001, userId=1003, amount=399.50, status=null, createTime=2026-01-29T10:30)
    }
}

// 非Spring环境调用
public class MapStructTest {
    public static void main(String[] args) {
        Order order = new Order();
        // 填充order数据...

        // 获取映射器实例
        OrderMapper mapper = OrderMapper.INSTANCE;
        // 实体类转DTO
        OrderDTO orderDTO = mapper.orderToOrderDTO(order);
    }
}

// 编译期自动生成的实现类
@Component
public class OrderMapperImpl implements OrderMapper {

    @Override
    public OrderDTO orderToOrderDTO(Order order) {
        if ( order == null ) {
            return null;
        }

        OrderDTO orderDTO = new OrderDTO();

        orderDTO.setId( order.getId() );
        orderDTO.setOrderNumber( order.getOrderNo() ); // 字段名映射
        orderDTO.setUserId( order.getUserId() );
        // BigDecimal转String，按dateFormat格式处理
        if ( order.getAmount() != null ) {
            orderDTO.setAmount( new DecimalFormat( "0.00" ).format( order.getAmount() ) );
        }
        // 调用自定义convertStatus方法转换状态
        orderDTO.setStatusDesc( convertStatus( order.getStatus() ) );
        // LocalDateTime转String，按dateFormat格式处理
        if ( order.getCreateTime() != null ) {
            orderDTO.setCreateTime( DateTimeFormatter.ofPattern( "yyyy-MM-dd HH:mm:ss" ).format( order.getCreateTime() ) );
        }

        return orderDTO;
    }

    // orderDTOToOrder方法实现类似，略...

    @Override
    public String convertStatus(Integer status) {
        // 自定义方法实现，略...
    }
}

@Mapper(componentModel = "spring")
public interface OrderMapper {
    // 单对象映射（已定义）
    OrderDTO orderToOrderDTO(Order order);

    // 集合映射：List<Order> -> List<OrderDTO>，MapStruct自动循环调用单对象方法
    List<OrderDTO> orderListToOrderDTOList(List<Order> orderList);

    // Set映射：Set<Order> -> Set<OrderDTO>
    Set<OrderDTO> orderSetToOrderDTOSet(Set<Order> orderSet);

    // Map映射：Map<Long, Order> -> Map<Long, OrderDTO>
    Map<Long, OrderDTO> orderMapToOrderDTOMap(Map<Long, Order> orderMap);
}

// 嵌套对象：用户实体类
@Data
public class User {
    private Long id;
    private String username;
    private String phone;
}

// 嵌套对象：用户DTO
@Data
public class UserDTO {
    private Long id;
    private String userName; // 与实体类username字段名不一致
    private String phone;
}

// 订单实体类（新增user字段，嵌套User对象）
@Data
public class Order {
    // 原有字段略...
    private User user; // 嵌套用户对象
}

// 订单DTO（新增userDTO字段，嵌套UserDTO对象）
@Data
public class OrderDTO {
    // 原有字段略...
    private UserDTO userDTO; // 嵌套用户DTO对象
}

// 映射接口：配置嵌套对象映射
@Mapper(componentModel = "spring")
public interface OrderMapper {
    // 嵌套对象映射：User -> UserDTO
    @Mapping(source = "username", target = "userName")
    UserDTO userToUserDTO(User user);

    // 订单映射：配置嵌套字段映射
    @Mapping(source = "user", target = "userDTO") // Order.user -> OrderDTO.userDTO
    @Mapping(source = "orderNo", target = "orderNumber")
    // 其他映射规则略...
    OrderDTO orderToOrderDTO(Order order);
}

// 自定义转换工具类（静态方法）
public class DateConvertUtil {
    // 自定义时间转换：LocalDateTime -> String（指定格式）
    public static String localDateTimeToString(LocalDateTime dateTime, String pattern) {
        if (dateTime == null || pattern == null) {
            return null;
        }
        return DateTimeFormatter.ofPattern(pattern).format(dateTime);
    }
}

// 映射接口引入工具类
@Mapper(componentModel = "spring", uses = {DateConvertUtil.class})
public interface OrderMapper {
    @Mapping(source = "createTime", target = "createTime", 
             expression = "java(DateConvertUtil.localDateTimeToString(order.getCreateTime(), \"yyyy-MM-dd\"))")
    OrderDTO orderToOrderDTO(Order order);
}

// 自定义转换器：BigDecimal -> String（支持多种格式）
public class BigDecimalToStringConverter implements Converter<BigDecimal, String> {
    @Override
    public String convert(BigDecimal source) {
        if (source == null) {
            return null;
        }
        // 金额大于1000添加千分位，否则保留两位小数
        return source.compareTo(new BigDecimal("1000")) > 0 
                ? new DecimalFormat("#,##0.00").format(source)
                : new DecimalFormat("0.00").format(source);
    }
}

// 映射接口引入转换器
@Mapper(componentModel = "spring", uses = {BigDecimalToStringConverter.class})
public interface OrderMapper {
    // 无需额外配置，MapStruct自动调用转换器
    @Mapping(source = "amount", target = "amount")
    OrderDTO orderToOrderDTO(Order order);
}

@Mapper(componentModel = "spring")
public interface OrderMapper {
    @Mapping(target = "statusDesc", ignore = true) // 忽略该字段，不映射
    @Mapping(source = "orderNo", target = "orderNumber", defaultValue = "未知订单号") // 源字段为null时，默认值为"未知订单号"
    @Mapping(source = "createTime", target = "createTime", defaultValue = "2026-01-01 00:00:00")
    OrderDTO orderToOrderDTO(Order order);
}

// 合并Order与User对象到OrderDetailDTO
@Data
public class OrderDetailDTO {
    private Long orderId;
    private String orderNumber;
    private BigDecimal amount;
    private String username; // 来自User对象
    private String phone; // 来自User对象
}

@Mapper(componentModel = "spring")
public interface OrderDetailMapper {
    // 多源映射：将Order和User合并为OrderDetailDTO
    @Mapping(source = "order.id", target = "orderId")
    @Mapping(source = "order.orderNo", target = "orderNumber")
    @Mapping(source = "order.amount", target = "amount")
    @Mapping(source = "user.username", target = "username")
    @Mapping(source = "user.phone", target = "phone")
    OrderDetailDTO mergeOrderAndUserToDTO(Order order, User user);
}