问题复盘｜NullPointerException - element cannot be mapped to a null key

报错信息

java.lang.NullPointerException: element cannot be mapped to a null key;

背景

在开发过程中，我们遇到了一个 NullPointerException 异常，错误信息显示某个元素不能被映射到一个 null 键。为了更好地理解和解决这个问题，我们进行了详细的排查和分析。

示例代码

问题代码示例如下：

import java.util.HashMap;
import java.util.Map;

public class NullPointerDemo {
    public static void main(String[] args) {
        Map<String, String> map = new HashMap<>();
        String key = getKey();
        map.put(key, "value");
    }

    public static String getKey() {
        // 模拟返回 null
        return null;
    }
}

排查过程

1. 检查调用堆栈

首先，我们查看了异常堆栈跟踪信息，确认异常发生的位置是在 map.put(key, "value") 这一行代码。

2. 查看代码逻辑

我们检查了代码逻辑，发现 getKey() 方法返回了 null，导致试图将 null 作为键插入 HashMap 中。

3. 添加检查和日志

为了确认 key 是否为 null，我们在插入键值对之前添加了 null 检查，并记录相关日志：

String key = getKey();
if (key == null) {
    throw new NullPointerException("Key cannot be null");
}
map.put(key, "value");

4. 调试或打印输出

使用调试工具或添加打印语句，确认 getKey() 方法确实返回了 null：

String key = getKey();
System.out.println("Key: " + key);
map.put(key, "value");

5. 检查数据源

我们还检查了 getKey() 方法的实现，确保它在所有情况下不会返回 null。

问题原因

问题的根本原因是 getKey() 方法返回了 null，而在将 null 作为键插入集合（如 HashMap）时引发了 NullPointerException。

后续如何避免

为避免类似问题，我们可以采取以下措施：

1. 添加空值检查：
   在将键值对插入集合之前，始终检查键是否为 null。

2. 改进方法实现：
   确保返回键值的方法（如 getKey()）不会返回 null。

3. 使用允许 null 键的集合：
   如果业务逻辑允许，选择使用允许 null 键的集合（如 HashMap），但依然需要注意空值处理。

4. 数据源验证：
   如果键值来自外部数据源（如数据库、文件、用户输入等），在处理前进行验证，确保数据源中的键值不包含 null。

修复后的代码示例

import java.util.HashMap;
import java.util.Map;

public class NullPointerDemo {
    public static void main(String[] args) {
        Map<String, String> map = new HashMap<>();
        String key = getKey();
        if (key == null) {
            throw new NullPointerException("Key cannot be null");
        }
        map.put(key, "value");
    }

    public static String getKey() {
        // 改进方法实现，确保不返回 null
        return "validKey"; // 或者根据逻辑生成一个非空键
    }
}

通过上述措施，我们可以有效地避免由于 null 键导致的 NullPointerException，从而提高代码的健壮性和可靠性。