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

Java Stream Collectors.toMap 详解：集合转 Map 用法 | 极客日志

// ❌ 传统方式：写循环，代码臃肿
Map<Integer, City> cityMap = new HashMap<>();
for (City city : cityList) {
    cityMap.put(city.getCityId(), city);
}

// ✅ Stream 方式：一行代码搞定
Map<Integer, City> cityMap = cityList.stream().collect(Collectors.toMap(City::getCityId, Function.identity()));

场景	说明	示例
ID-对象映射	通过 ID 快速查找对象	用户 ID -> 用户对象
ID-属性映射	提取对象的某个属性	城市 ID -> 城市名称
分组聚合	按某个维度统计	销售员 -> 总销售额
去重转换	处理键冲突情况	自定义冲突策略

public static <T, K, U> Collector<T, ?, Map<K, U>> toMap(
    Function<? super T, ? extends K> keyMapper, // 键提取函数
    Function<? super T, ? extends U> valueMapper // 值提取函数
)

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

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 类型
Stream 流	使用哪个 toMap?	双参数版本
HashMap	三参数版本	四参数版本
自定义合并策略	TreeMap/LinkedHashMap 等

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;
}

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 的名称：广州

@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 
城市名称：北京

@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 天津) 
保留旧值：深圳 
使用新值：天津 
合并值：深圳，天津

@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}

@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=深圳}

@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";
    }
}

@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);
}

@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;
}

@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("未知")
        )
    );
}

@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 // 合并策略
        )
    );
}

@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);
}

@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");
}

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

Map 类型	插入 10 万条耗时	特点
HashMap	28ms	最快，无序
LinkedHashMap	32ms	稍慢，保持顺序
TreeMap	85ms	最慢，自动排序
ConcurrentHashMap	35ms	线程安全

场景	推荐写法	说明
简单 ID-对象映射	`toMap(keyMapper, Function.identity())`	最常用
ID-属性映射	`toMap(keyMapper, valueMapper)`	提取特定属性
可能有重复键	提供合并函数	避免异常
需要有序 Map	指定 LinkedHashMap	保持插入顺序
需要排序 Map	指定 TreeMap	按键排序
并行流处理	指定 ConcurrentHashMap	线程安全

// 最常用模板：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
    )
);

特性	说明
核心功能	将 List 转换为 Map，实现快速查找
三个版本	2 参数（基础）、3 参数（冲突处理）、4 参数（指定 Map）
常见用途	ID 映射、属性提取、分组聚合
注意事项	null 值处理、键冲突、并发安全
性能表现	与传统循环相当，代码更优雅

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

引言：从 List 到 Map 的优雅转换

一、Collectors.toMap 概述

1.1 什么是 Collectors.toMap？

1.2 适用场景

二、三种重载方法详解

2.1 两个参数：基础版

2.2 三个参数：冲突处理版

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

三、实战示例

3.1 准备实体类

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

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

3.4 示例 3：处理键冲突

3.5 示例 4：分组聚合统计

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

四、高级应用技巧

4.1 复杂对象转换

4.2 条件过滤

4.3 多字段组合键

五、注意事项与常见陷阱

5.1 Null 值问题

5.2 键重复问题

5.3 并行流问题

六、性能对比

6.1 传统循环 vs Stream

6.2 不同 Map 实现性能

七、最佳实践总结

7.1 使用建议

7.2 常见问题检查清单

7.3 代码模板

总结

更多推荐文章

相关免费在线工具

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

引言：从 List 到 Map 的优雅转换

一、Collectors.toMap 概述

1.1 什么是 Collectors.toMap？

1.2 适用场景

二、三种重载方法详解

2.1 两个参数：基础版

2.2 三个参数：冲突处理版

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

三、实战示例

3.1 准备实体类

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

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

3.4 示例 3：处理键冲突

3.5 示例 4：分组聚合统计

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

四、高级应用技巧

4.1 复杂对象转换

4.2 条件过滤

4.3 多字段组合键

五、注意事项与常见陷阱

5.1 Null 值问题

5.2 键重复问题

5.3 并行流问题

六、性能对比

6.1 传统循环 vs Stream

6.2 不同 Map 实现性能

七、最佳实践总结

7.1 使用建议

7.2 常见问题检查清单

7.3 代码模板

总结

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具