✨ 一、前言

在 Java 8 引入的 Stream 流处理中，Collectors.toMap() 是我们转换集合为 Map 的高频操作器，它让代码变得非常简洁。但这行优雅的代码背后，其实隐藏着一个高频踩坑点——当 value 为 null 时会直接抛出 NullPointerException！

今天我们将通过一个真实例子 + 最简示例 + 报错分析 + 正确写法 + 常见疑问解答的方式，把这个坑彻底讲清楚，让你告别 Collectors.toMap() 的空指针炸锅！

🧨 二、问题重现：Collectors.toMap 遇到 null 会直接炸

我们先来看一个最简版的例子，完全 new 对象，无任何依赖：

import java.util.*;
import java.util.stream.Collectors;

public class ToMapNullValueDemo {
    static class Person {
        private Integer id;
        private String name;

        public Person(Integer id, String name) {
            this.id = id;
            this.name = name;
        }

        public Integer getId() { return id; }
        public String getName() { return name; }
    }

    public static void main(String[] args) {
        List<Person> people = Arrays.asList(
            new Person(1, "Alice"),
            new Person(2, null),       // 🚨 null value!
            new Person(3, "Charlie")
        );

        Map<Integer, String> map = people.stream()
            .collect(Collectors.toMap(
                Person::getId,
                Person::getName // 这里的 null 会导致崩溃！
            ));

        System.out.println(map);
    }
}

💥 输出结果

Exception in thread "main" java.lang.NullPointerException
	at java.util.HashMap.merge(HashMap.java:1225)
	at java.util.stream.Collectors.lambda$toMap$58(Collectors.java:1320)

是的，直接崩！

🔍 三、为什么会报错？（源码揭秘）

Collectors.toMap() 背后的实现是这样的：

toMap(keyMapper, valueMapper, throwingMerger(), HashMap::new)

它调用了 Map.merge(k, v, remappingFunction)，而这个方法明确规定：

如果 value 为 null，就会抛出 NullPointerException。

✅ 四、如何优雅规避空指针？

✅ 方法 1：使用 getOrDefault

Map<Integer, String> map = people.stream()
    .collect(Collectors.toMap(
        Person::getId,
        p -> Optional.ofNullable(p.getName()).orElse("未知")
    ));

或者：

Map<Integer, String> map = people.stream()
    .collect(Collectors.toMap(
        Person::getId,
        p -> p.getName() != null ? p.getName() : "未知"
    ));

✅ 方法 2：业务场景示例（通知列表）

Map<Integer, Integer> notificationId = notificationList.stream()
    .collect(Collectors.toMap(
        NotificationVO::getId,
        n -> eventIdToTeacherIdMap.getOrDefault(n.getLinkedId(), -1) // 防御性写法
    ));

❗五、补充：key 重复也会炸！

List<String> list = Arrays.asList("a", "b", "a");

Map<String, Integer> map = list.stream()
    .collect(Collectors.toMap(
        s -> s,
        s -> 1
    ));

💥 报错：

IllegalStateException: Duplicate key a

✅ 正确写法：

.collect(Collectors.toMap(
    s -> s,
    s -> 1,
    (v1, v2) -> v1 // 合并策略：保留旧值
));

🧠 六、那普通 Map 呢？允许 null 吗？

很多人以为：“我直接 put(key, null) 都行啊，为什么 Stream 就炸了？”

我们来验证一下：

Map<Integer, String> map = new HashMap<>();
map.put(1, "Apple");
map.put(2, null);  // ✅ value 为 null 没问题
System.out.println(map);

✅ 输出：

{1=Apple, 2=null}

🔍 结论：

⚠️ Collectors.toMap() 使用 Map.merge()，所以它不能容忍 value 为 null，这和 map.put() 是两回事！

📌 七、总结与建议

✅ 八、建议你养成防御性编程习惯

每当你用 .toMap() 时，问自己：

• value 有可能为 null 吗？

• key 有可能重复吗？

能用 .getOrDefault() 就别冒险！
能预防异常的地方，不要假设不会出问题。

💬 九、结语

Collectors.toMap() 是 Java 8 Stream 中非常强大的工具，但它对 null 不太宽容，稍有不慎就可能在线上环境踩雷。

希望这篇博客能让你彻底掌握它的使用细节，写出更稳健的 Java 代码！

📌 如果你觉得这篇文章对你有帮助，欢迎收藏、点赞、转发！
📌 有其他 Stream 踩坑想法？评论区见！