Java Stream Collectors.toMap 详解：集合转 Map 用法

特点：

• 可处理键冲突
• 自定义合并策略

2.3 四个参数：指定 Map 实现版

public static <T, K, U, M extends Map<K, U>> Collector<T, ?, M> toMap(
    Function<? super T, ? extends K> keyMapper, // 键提取函数
    Function<? super T, ? extends U> valueMapper, // 值提取函数
    BinaryOperator<U> mergeFunction, // 冲突合并函数
    Supplier<M> mapSupplier // Map 工厂
)

特点：

• 可指定 Map 类型（HashMap、TreeMap、LinkedHashMap 等）
• 最大灵活性

三、实战示例

3.1 准备实体类

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import java.math.BigDecimal;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class City {
    private Integer cityId;
    private String cityName;
}

@Data
@NoArgsConstructor
@AllArgsConstructor
public class SalesRecord {
    private String salesPerson;
    private BigDecimal amount;
}

3.2 示例 1：ID 到名称的映射

import org.junit.jupiter.api.Test;
import java.util.*;
import java.util.stream.Collectors;

public class ToMapExampleTest {
    @Test
    public void testIdToNameMap() {
        List<City> cityList = Arrays.asList(
            new City(1, "北京"),
            new City(2, "上海"),
            new City(3, "广州"),
            new City(4, "深圳")
        );
        // 转换为 Map<ID, 城市名称>
        Map<Integer, String> cityNameMap = cityList.stream().collect(
            Collectors.toMap(
                City::getCityId,      // key: 城市 ID
                City::getCityName     // value: 城市名称
            )
        );
        System.out.println("城市名称映射：" + cityNameMap);
        // 通过 ID 快速获取城市名称
        System.out.println("城市 ID 3 的名称：" + cityNameMap.get(3));
    }
}

输出：

城市名称映射：{1=北京，2=上海，3=广州，4=深圳} 
城市 ID 3 的名称：广州

3.3 示例 2：ID 到对象的映射

@Test
public void testIdToObjectMap() {
    List<City> cityList = Arrays.asList(
        new City(1, "北京"),
        new City(2, "上海"),
        new City(3, "广州"),
        new City(4, "深圳")
    );
    // 方式 1：使用 lambda
    Map<Integer, City> cityMap1 = cityList.stream().collect(
        Collectors.toMap(
            city -> city.getCityId(),
            city -> city
        )
    );
    // 方式 2：使用方法引用（推荐）
    Map<Integer, City> cityMap2 = cityList.stream().collect(
        Collectors.toMap(
            City::getCityId,
            Function.identity() // 等同于 city -> city
        )
    );
    City city = cityMap2.get(1);
    System.out.println("城市 ID: " + city.getCityId());
    System.out.println("城市名称：" + city.getCityName());
}

输出：

城市 ID: 1 
城市名称：北京

3.4 示例 3：处理键冲突

@Test
public void testDuplicateKeyHandling() {
    List<City> cityList = Arrays.asList(
        new City(1, "北京"),
        new City(2, "上海"),
        new City(3, "广州"),
        new City(4, "深圳"),
        new City(4, "天津") // 重复 ID
    );
    
    // 抛出异常版本（默认）
    try {
        Map<Integer, String> map = cityList.stream().collect(
            Collectors.toMap(City::getCityId, City::getCityName)
        );
    } catch (IllegalStateException e) {
        System.out.println("默认行为：键重复抛出异常 - " + e.getMessage());
    }
    
    // 保留旧值
    Map<Integer, String> keepOldMap = cityList.stream().collect(
        Collectors.toMap(
            City::getCityId,
            City::getCityName,
            (oldValue, newValue) -> oldValue // 保留旧值
        )
    );
    System.out.println("保留旧值：" + keepOldMap.get(4));
    
    // 使用新值
    Map<Integer, String> useNewMap = cityList.stream().collect(
        Collectors.toMap(
            City::getCityId,
            City::getCityName,
            (oldValue, newValue) -> newValue // 使用新值
        )
    );
    System.out.println("使用新值：" + useNewMap.get(4));
    
    // 合并值
    Map<Integer, String> mergeMap = cityList.stream().collect(
        Collectors.toMap(
            City::getCityId,
            City::getCityName,
            (oldValue, newValue) -> oldValue + ", " + newValue // 合并
        )
    );
    System.out.println("合并值：" + mergeMap.get(4));
}

输出：

默认行为：键重复抛出异常 - Duplicate key 4 (attempted merging values 深圳 and 天津) 
保留旧值：深圳 
使用新值：天津 
合并值：深圳，天津

3.5 示例 4：分组聚合统计

@Test
public void testAggregation() {
    List<SalesRecord> records = Arrays.asList(
        new SalesRecord("张三", new BigDecimal("1000")),
        new SalesRecord("李四", new BigDecimal("2000")),
        new SalesRecord("张三", new BigDecimal("980")),
        new SalesRecord("王五", new BigDecimal("1500")),
        new SalesRecord("李四", new BigDecimal("1200"))
    );
    
    // 计算每个人的总销售额
    Map<String, BigDecimal> totalMap = records.stream().collect(
        Collectors.toMap(
            SalesRecord::getSalesPerson,
            SalesRecord::getAmount,
            BigDecimal::add // 合并函数：相加
        )
    );
    System.out.println("总销售额：" + totalMap);
    
    // 计算每个人的最大销售额
    Map<String, BigDecimal> maxMap = records.stream().collect(
        Collectors.toMap(
            SalesRecord::getSalesPerson,
            SalesRecord::getAmount,
            BigDecimal::max // 取最大值
        )
    );
    System.out.println("最大销售额：" + maxMap);
    
    // 计算每个人的最小销售额
    Map<String, BigDecimal> minMap = records.stream().collect(
        Collectors.toMap(
            SalesRecord::getSalesPerson,
            SalesRecord::getAmount,
            BigDecimal::min // 取最小值
        )
    );
    System.out.println("最小销售额：" + minMap);
}

输出：

总销售额：{李四=3200, 张三=1980, 王五=1500} 
最大销售额：{李四=2000, 张三=1000, 王五=1500} 
最小销售额：{李四=1200, 张三=980, 王五=1500}

3.6 示例 5：指定 Map 实现类型

@Test
public void testSpecifyMapType() {
    List<City> cityList = Arrays.asList(
        new City(2, "上海"),
        new City(1, "北京"),
        new City(4, "深圳"),
        new City(3, "广州")
    );
    
    // 默认 HashMap（无序）
    Map<Integer, String> hashMap = cityList.stream().collect(
        Collectors.toMap(
            City::getCityId,
            City::getCityName,
            (old, now) -> old
        )
    );
    System.out.println("HashMap (无序): " + hashMap);
    
    // 使用 LinkedHashMap（保持插入顺序）
    Map<Integer, String> linkedHashMap = cityList.stream().collect(
        Collectors.toMap(
            City::getCityId,
            City::getCityName,
            (old, now) -> old,
            LinkedHashMap::new // 指定 LinkedHashMap
        )
    );
    System.out.println("LinkedHashMap (插入顺序): " + linkedHashMap);
    
    // 使用 TreeMap（按键排序）
    Map<Integer, String> treeMap = cityList.stream().collect(
        Collectors.toMap(
            City::getCityId,
            City::getCityName,
            (old, now) -> old,
            TreeMap::new // 指定 TreeMap
        )
    );
    System.out.println("TreeMap (键排序): " + treeMap);
    
    // 使用 ConcurrentHashMap（线程安全）
    Map<Integer, String> concurrentMap = cityList.parallelStream().collect(
        Collectors.toMap(
            City::getCityId,
            City::getCityName,
            (old, now) -> old,
            ConcurrentHashMap::new // 线程安全的 Map
        )
    );
    System.out.println("ConcurrentHashMap: " + concurrentMap);
}

输出：

HashMap (无序): {1=北京，2=上海，3=广州，4=深圳} 
LinkedHashMap (插入顺序): {2=上海，1=北京，4=深圳，3=广州} 
TreeMap (键排序): {1=北京，2=上海，3=广州，4=深圳} 
ConcurrentHashMap: {1=北京，2=上海，3=广州，4=深圳}

四、高级应用技巧

4.1 复杂对象转换

@Test
public void testComplexTransformation() {
    List<City> cityList = Arrays.asList(
        new City(1, "北京"),
        new City(2, "上海")
    );
    // 转换为 DTO 对象
    Map<Integer, CityDTO> dtoMap = cityList.stream().collect(
        Collectors.toMap(
            City::getCityId,
            city -> new CityDTO(
                city.getCityId(),
                city.getCityName(),
                "中国",
                getCityCode(city.getCityName())
            )
        )
    );
    System.out.println("DTO 映射：" + dtoMap);
}

// 简化的 DTO 类
@Data
@AllArgsConstructor
class CityDTO {
    private Integer id;
    private String name;
    private String country;
    private String code;
}

private String getCityCode(String cityName) {
    switch (cityName) {
        case "北京": return "BJ";
        case "上海": return "SH";
        default: return "UNKNOWN";
    }
}

4.2 条件过滤

@Test
public void testConditionalMapping() {
    List<City> cityList = Arrays.asList(
        new City(1, "北京"),
        new City(2, "上海"),
        new City(3, "广州"),
        new City(4, "深圳"),
        new City(5, null) // 可能为 null
    );
    
    // 过滤掉 null 值
    Map<Integer, String> filteredMap = cityList.stream()
        .filter(city -> city.getCityName() != null)
        .collect(Collectors.toMap(City::getCityId, City::getCityName));
    System.out.println("过滤 null: " + filteredMap);
    
    // 提供默认值
    Map<Integer, String> defaultMap = cityList.stream().collect(
        Collectors.toMap(
            City::getCityId,
            city -> Optional.ofNullable(city.getCityName()).orElse("未知")
        )
    );
    System.out.println("默认值：" + defaultMap);
}

4.3 多字段组合键

@Test
public void testCompositeKey() {
    List<Order> orders = Arrays.asList(
        new Order("202501", "A001", new BigDecimal("100")),
        new Order("202501", "A002", new BigDecimal("200")),
        new Order("202502", "A001", new BigDecimal("150"))
    );
    // 使用月份 + 客户 ID 作为组合键
    Map<String, BigDecimal> monthlyCustomerTotal = orders.stream().collect(
        Collectors.toMap(
            order -> order.getMonth() + "_" + order.getCustomerId(),
            Order::getAmount,
            BigDecimal::add
        )
    );
    System.out.println("月度客户汇总：" + monthlyCustomerTotal);
}

@Data
@AllArgsConstructor
class Order {
    private String month;
    private String customerId;
    private BigDecimal amount;
}

五、注意事项与常见陷阱

5.1 Null 值问题

@Test
public void testNullValueProblem() {
    List<City> cityList = Arrays.asList(
        new City(1, "北京"),
        new City(2, "上海"),
        new City(3, "广州"),
        new City(4, "深圳"),
        new City(5, null) // 值为 null
    );
    
    // ❌ 会抛出 NullPointerException
    try {
        Map<Integer, String> map = cityList.stream().collect(
            Collectors.toMap(City::getCityId, City::getCityName)
        );
    } catch (NullPointerException e) {
        System.out.println("NullPointerException: " + e.getMessage());
    }
    
    // ✅ 解决方案 1：过滤 null 值
    Map<Integer, String> solution1 = cityList.stream()
        .filter(city -> city.getCityName() != null)
        .collect(Collectors.toMap(City::getCityId, City::getCityName));
    
    // ✅ 解决方案 2：提供默认值
    Map<Integer, String> solution2 = cityList.stream().collect(
        Collectors.toMap(
            City::getCityId,
            city -> Optional.ofNullable(city.getCityName()).orElse("未知")
        )
    );
}

5.2 键重复问题

@Test
public void testDuplicateKeyProblem() {
    List<City> cityList = Arrays.asList(
        new City(1, "北京"),
        new City(2, "上海"),
        new City(1, "天津") // 重复键
    );
    
    // ❌ 抛出 IllegalStateException
    try {
        Map<Integer, String> map = cityList.stream().collect(
            Collectors.toMap(City::getCityId, City::getCityName)
        );
    } catch (IllegalStateException e) {
        System.out.println("IllegalStateException: " + e.getMessage());
    }
    
    // ✅ 必须提供合并函数
    Map<Integer, String> map = cityList.stream().collect(
        Collectors.toMap(
            City::getCityId,
            City::getCityName,
            (oldValue, newValue) -> oldValue // 合并策略
        )
    );
}

5.3 并行流问题

@Test
public void testParallelStream() {
    List<City> cityList = Arrays.asList(
        new City(1, "北京"),
        new City(2, "上海"),
        new City(3, "广州"),
        new City(4, "深圳")
    );
    
    // 并行流中使用 toMap
    Map<Integer, String> map = cityList.parallelStream().collect(
        Collectors.toMap(
            City::getCityId,
            City::getCityName,
            (v1, v2) -> v1, // 合并函数在并行流中很重要！
            ConcurrentHashMap::new // 推荐使用 ConcurrentHashMap
        )
    );
    System.out.println("并行流结果：" + map);
}

六、性能对比

6.1 传统循环 vs Stream

@Test
public void testPerformance() {
    List<City> cityList = new ArrayList<>();
    for (int i = 0; i < 100000; i++) {
        cityList.add(new City(i, "City" + i));
    }
    
    // 传统循环
    long start = System.currentTimeMillis();
    Map<Integer, City> loopMap = new HashMap<>();
    for (City city : cityList) {
        loopMap.put(city.getCityId(), city);
    }
    long loopTime = System.currentTimeMillis() - start;
    
    // Stream
    start = System.currentTimeMillis();
    Map<Integer, City> streamMap = cityList.stream().collect(
        Collectors.toMap(City::getCityId, Function.identity())
    );
    long streamTime = System.currentTimeMillis() - start;
    
    System.out.println("传统循环耗时：" + loopTime + "ms");
    System.out.println("Stream 耗时：" + streamTime + "ms");
    System.out.println("性能差异：" + (loopTime - streamTime) + "ms");
}

结果（10 万条数据）：

传统循环耗时：35ms 
Stream 耗时：28ms 
性能差异：7ms

6.2 不同 Map 实现性能

七、最佳实践总结

7.1 使用建议

7.2 常见问题检查清单

• value 是否为 null？ → 需要过滤或提供默认值
• key 是否可能重复？ → 需要提供合并函数
• 是否需要保持顺序？ → 考虑 LinkedHashMap
• 是否在并行流中使用？ → 考虑 ConcurrentHashMap
• 是否需要排序？ → 考虑 TreeMap

7.3 代码模板

// 最常用模板：ID 到对象映射
Map<KeyType, Entity> map = list.stream().collect(
    Collectors.toMap(
        Entity::getKeyMethod,
        Function.identity(),
        (existing, replacement) -> existing // 保留旧值
    )
);

// 分组聚合模板
Map<KeyType, ValueType> aggMap = list.stream().collect(
    Collectors.toMap(
        Item::getKey,
        Item::getValue,
        (v1, v2) -> v1 + v2 // 自定义合并逻辑
    )
);

// 有序 Map 模板
Map<KeyType, ValueType> orderedMap = list.stream().collect(
    Collectors.toMap(
        Item::getKey,
        Item::getValue,
        (v1, v2) -> v1,
        LinkedHashMap::new // 或 TreeMap::new
    )
);

总结

一句话总结：

Collectors.toMap 是 Java Stream 中最实用的收集器之一，掌握它能让你用一行代码搞定过去需要写循环的复杂转换！