// 痛苦的回忆：手动循环
List<UserVO> voList = new ArrayList<>();
for (UserEntity entity : entityList) {
    UserVO vo = new UserVO();
    BeanUtils.copyProperties(entity, vo); // 还要处理异常
    voList.add(vo);
}
return voList;

@Mapper(componentModel = "spring", imports = {UUID.class})
public interface UserMapper {

    // 1. 单对象转换 (上一章已经写好)
    // MapStruct 会在生成集合转换时，自动调用这个方法处理每一个元素
    @Mappings({
        @Mapping(source = "emailAddress", target = "email", defaultValue = "no-email@example.com"),
        @Mapping(target = "source", constant = "PC_BROWSER"),
        // ... 其他配置保持不变
    })
    UserVO toVO(UserEntity entity);

    // 2. 新增：集合转换
    // 你不需要加任何 @Mapping 注解，框架会自动检测泛型 <UserEntity> -> <UserVO>
    // 并自动循环调用上面的 toVO 方法
    List<UserVO> toVOList(List<UserEntity> entityList);
}

@Override
public List<UserVO> toVOList(List<UserEntity> entityList) {
    // 1. 自动判空：如果入参 list 是 null，直接返回 null
    if ( entityList == null ) {
        return null;
    }

    // 2. 自动初始化目标集合，大小与源集合一致，避免扩容开销
    List<UserVO> list = new ArrayList<UserVO>( entityList.size() );
    
    // 3. 自动生成增强 for 循环
    for ( UserEntity userEntity : entityList ) {
        // 4. 循环调用单对象转换方法 toVO(userEntity)
        list.add( toVO( userEntity ) );
    }

    return list;
}

if ( entityList == null ) {
    return null; // 返回 null
}

import org.mapstruct.NullValueIterableMappingStrategy;

// 增加 nullValueIterableMappingStrategy 配置
@Mapper(
    componentModel = "spring", 
    imports = {UUID.class},
    nullValueIterableMappingStrategy = NullValueIterableMappingStrategy.RETURN_DEFAULT
)
public interface UserMapper {
    // ... 方法保持不变
}

@Override
public List<UserVO> toVOList(List<UserEntity> entityList) {
    if ( entityList == null ) {
        // 变化点：现在返回一个新的空 ArrayList，而不是 null
        return new ArrayList<UserVO>();
    }
    // ... 循环逻辑
}

/**
 * 场景一：Map <String, Date> -> Map <String, String>
 * 需求：Key 保持不变，Value 中的日期格式化为 yyyy-MM-dd
 */
@MapMapping(valueDateFormat = "yyyy-MM-dd")
Map<String, String> mapValueFormatting(Map<String, LocalDateTime> sourceMap);

@Override
public Map<String, String> mapValueFormatting(Map<String, LocalDateTime> sourceMap) {
    if ( sourceMap == null ) {
        return null;
    }
    // 2. 目标 Map 优化初始化：
    // - 采用 LinkedHashMap：保留源 Map 的键值对顺序（与 HashMap 相比，LinkedHashMap 维护插入顺序）
    // - 容量计算逻辑：Math.max( (int) (sourceMap.size() / .75f) + 1, 16 )
    //   原理：HashMap/LinkedHashMap 的负载因子默认是 0.75，当元素数量达到 容量*负载因子 时会触发扩容
    //   这里通过 sourceMap.size() / 0.75f + 1 计算出「刚好能容纳所有元素且不触发扩容」的最小容量
    //   再与 16（集合默认初始容量）取最大值，既避免扩容损耗，又保证最小初始容量的合理性
    Map<String, String> map = new LinkedHashMap<String, String>( Math.max( (int) ( sourceMap.size() / .75f ) + 1, 16 ) );

    // 3. 遍历源 Map 并执行 Value 转换：
    for ( java.util.Map.Entry<String, LocalDateTime> entry : sourceMap.entrySet() ) {
        String key = entry.getKey(); // 键直接复用，无需转换（类型一致）
        
        // 核心逻辑：LocalDateTime 类型 Value -> 格式化字符串
        // MapStruct 自动生成的格式化器实例（单例/复用设计）
        String value = dateTimeFormatter_yyyy_MM_dd_0159776256.format( entry.getValue() );
        
        map.put( key, value ); // 转换后的键值对放入目标 Map
    }

    return map; // 返回格式化后的目标 Map
}

// 错误示范：MapStruct 无法自动实现
UserEntity mapToEntity(Map<String, Object> map);

public UserEntity mapToEntity(Map<String, Object> map) {
    if ( map == null ) return null;
    return new UserEntity(); // 属性全都没赋值！
}

import cn.hutool.core.bean.BeanUtil;
import cn.hutool.core.bean.copier.CopyOptions;

@Mapper(componentModel = "spring")
public interface UserMapper {

    // ... 其他方法 ...

    /**
     * 场景二：Map <String, Object> -> Bean
     * 痛点解决：利用 default 方法 + Hutool 反射实现
     * 价值：对外屏蔽了实现细节，Service 层依然只调用 UserMapper
     */
    default UserEntity mapToEntity(Map<String, Object> map) {
        if (map == null) {
            return null;
        }
        // 使用 Hutool 的 BeanUtil，支持驼峰/下划线自动转换
        // 配置项表示忽略转换错误与 忽略 null 值
        return BeanUtil.toBean(map, UserEntity.class, CopyOptions.create().ignoreError().ignoreNullValue());
    }
}

@GetMapping("/testMap")
public Map<String, Object> testMap() {
    Map<String, Object> result = new LinkedHashMap<>();

    // 1. 验证 Map <Date> -> Map <String>
    Map<String, LocalDateTime> sourceMap = new HashMap<>();
    sourceMap.put("startTime", LocalDateTime.now());
    // MapStruct 自动处理格式化
    Map<String, String> formattedMap = userMapper.mapValueFormatting(sourceMap);
    result.put("scene1_formatting", formattedMap);

    // 2. 验证 Map <Object> -> Bean
    Map<String, Object> inputMap = new HashMap<>();
    inputMap.put("username", "map_user");
    inputMap.put("emailAddress", "map@test.com"); // 注意：BeanUtil 支持属性自动匹配
    inputMap.put("age", 18); // 多余字段，应该被忽略
    
    // Hutool 兜底处理动态转换
    UserEntity entity = userMapper.mapToEntity(inputMap);
    result.put("scene2_bean", entity);

    return result;
}

@Mapper(
    componentModel = "spring",
    // 针对 List/Set 返回空集合
    nullValueIterableMappingStrategy = NullValueIterableMappingStrategy.RETURN_DEFAULT,
    // 针对 Map 返回空 Map
    nullValueMapMappingStrategy = NullValueMapMappingStrategy.RETURN_DEFAULT
)
public interface BaseMapper {
    // ...
}

// 1. 基础的 List 转换 (MapStruct 自动生成)
// 这是地基，必须保留，供下面的 default 方法调用
List<UserVO> toVOList(List<UserEntity> entityList);

/**
 * 2. 高级聚合：List -> Map <Long, UserVO>
 * 利用 Java 8 default 方法，结合 MapStruct 和 Stream API
 */
default Map<Long, UserVO> toVOMap(List<UserEntity> entityList) {
    // 1. 安全防御：复用空集合策略
    if (entityList == null || entityList.isEmpty()) {
        return java.util.Collections.emptyMap();
    }
    
    // 2. 调用 MapStruct 生成的方法，先完成 Object -> Object 的属性转换
    List<UserVO> voList = toVOList(entityList);
    
    // 3. 使用 Stream API 进行聚合
    return voList.stream()
            .collect(java.util.stream.Collectors.toMap(
                    UserVO::getId,       // Key: 使用 ID
                    vo -> vo,            // Value: VO 对象本身
                    // MergeFunction (冲突解决策略): 
                    // 如果数据库中意外出现了重复 ID (脏数据)，取第一个，防止抛出 IllegalStateException
                    (v1, v2) -> v1       
            ));
}

// ... 注入 UserMapper

/**
 * 验证场景 1：List 转换与空值策略
 * 预期：
 * 1. 正常数据正常转换
 * 2. 传入 null 时，返回 [] 而不是 null
 */
@GetMapping("/list")
public List<UserVO> testList(@RequestParam(required = false) boolean mockNull) {
    if (mockNull) {
        // 测试空值策略：传入 null
        return userMapper.toVOList(null);
    }

    // 模拟数据
    List<UserEntity> list = new ArrayList<>();
    UserEntity u1 = new UserEntity();
    u1.setId(1L);
    u1.setEmailAddress("user1@test.com");
    
    UserEntity u2 = new UserEntity();
    u2.setId(2L);
    // u2 没有 email，测试 List 循环中的默认值逻辑是否生效
    
    list.add(u1);
    list.add(u2);
    
    return userMapper.toVOList(list);
}

/**
 * 验证场景 2：Stream 聚合 (List -> Map)
 * 预期：返回以 ID 为 Key 的 JSON 对象
 */
@GetMapping("/mapAggregate")
public Map<Long, UserVO> testMapAggregate() {
    List<UserEntity> list = new ArrayList<>();
    
    UserEntity u1 = new UserEntity();
    u1.setId(100L);
    u1.setUsername("Admin");

    UserEntity u2 = new UserEntity();
    u2.setId(200L);
    u2.setUsername("Guest");
    
    // 模拟脏数据：重复 ID，验证 toMap 的 mergeFunction 是否生效
    UserEntity u3_duplicate = new UserEntity();
    u3_duplicate.setId(100L); 
    u3_duplicate.setUsername("Admin_Duplicate");

    list.add(u1);
    list.add(u2);
    list.add(u3_duplicate);

    return userMapper.toVOMap(list);
}

// UserMapper.java

// 1. 定义单对象转换 (基础)
UserVO toVO(UserEntity entity);

// 2. 定义列表转换 (核心)
// MapStruct 自动生成循环代码，并复用 toVO 的配置
List<UserVO> toVOList(List<UserEntity> entityList);

// UserMapper.java

@Mapper(
    componentModel = "spring",
    // 核心配置：List/Set 入参为 null 时，返回 new ArrayList<>()
    nullValueIterableMappingStrategy = NullValueIterableMappingStrategy.RETURN_DEFAULT,
    // 核心配置：Map 入参为 null 时，返回 new LinkedHashMap<>()
    nullValueMapMappingStrategy = NullValueMapMappingStrategy.RETURN_DEFAULT
)
public interface UserMapper {
    // ...
}

// UserMapper.java

// 1. 基础转换 (由 MapStruct 实现)
List<UserVO> toVOList(List<UserEntity> list);

// 2. 自定义聚合 (由 Java 8 Default 方法实现)
default Map<Long, UserVO> toVOMap(List<UserEntity> list) {
    if (list == null) return Collections.emptyMap();
    
    return toVOList(list).stream() // 先转换内容
        .collect(Collectors.toMap(
            UserVO::getId,         // Key: 用户 ID
            vo -> vo,              // Value: VO 对象
            (v1, v2) -> v1         // Merge: 若 ID 重复，取第一个 (防崩溃)
        ));
}

// UserMapper.java

// 引入 Hutool 的 BeanUtil
import cn.hutool.core.bean.BeanUtil;

default UserEntity mapToEntity(Map<String, Object> map) {
    if (map == null) return null;
    
    // 使用反射工具兜底，实现动态 Key 匹配
    // ignoreError: 忽略转换失败的字段
    return BeanUtil.toBean(map, UserEntity.class);
}