如何在 Java 中使用 Collections.singletonMap() 创建一个包含单对键值且不可修改的映射表

Collections.singletonMap()：创建单键值对、线程安全且不可修改的轻量级 Map 的最简洁方式

在 Ja va 开发中，你是否遇到过这样的场景：只需要一个简单的键值对映射，既不想引入完整的 HashMap 开销，又希望它是线程安全且不可修改的？

答案就是 Collections.singletonMap()。这个方法堪称是创建单元素、不可变映射表的“瑞士军刀”——它返回一个轻量级的内部 SingletonMap 实例，底层不依赖哈希表或红黑树，内存占用极低。无论是作为默认值、API 响应，还是临时占位符，它都能优雅胜任。

基本用法：传入键和值即可

方法签名非常直观，是一个静态泛型方法：

public static  Map singletonMap(K key, V value)

使用时，直接传入键和值，类型交给编译器推断，简洁到极致：

Map singleMap = Collections.singletonMap("age", 25);

这样一来，singleMap 就成了一个只包含 "age" → 25 的映射。后续任何试图修改它的操作，比如 put、remove 或 clear，都会立刻抛出 UnsupportedOperationException。这从根本上杜绝了意外修改的风险。

话说回来，如果你想系统掌握这类高效工具，一份全面的“Ja va免费学习笔记（深入）”会是很好的助力。

关键特性与注意事项

理解以下几个特性，能帮你更好地驾驭这个方法：

• 彻底的不可变性：不仅不能增删改键值对，就连通过 entrySet() 或 keySet() 获取的迭代器进行修改也会被阻止。
• 天生的线程安全：由于状态固定且无法改变，多个线程并发读取绝对安全，无需任何同步措施。
• 轻量级的专属实现：它返回的不是常见的 HashMap，而是一个内部私有静态类 SingletonMap。结构简单，没有多余的开销。
• 支持 null 键值：只要泛型类型允许，键和值都可以为 null，例如 Collections.singletonMap(null, "unknown") 是完全合法的。
• 仅限单元素：如果需要包含多个键值对的不可变映射，就得考虑其他方案了，比如 Ja va 9 引入的 Map.of() 或者 Gua va 的 ImmutableMap.of()。

常见适用场景

那么，哪些地方最适合用它呢？下面这几个场景非常典型：

• 作为方法参数的默认值：避免传入 null 或空的 Map，让意图更清晰。例如：processOptions(Collections.singletonMap("debug", true))。
• 构建简洁的 API 响应体：在 RESTful 接口中返回一个简单的状态或结果时，代码既干净又安全：return Collections.singletonMap("status", "success");。
• 在 Stream 流水线中作为中间映射：例如在收集器中进行转换：list.stream().collect(Collectors.toMap(x -> x, x -> Collections.singletonMap("type", "item")))。
• 替代冗长的样板代码：比起手动创建 HashMap、调用 put、再包装成不可变映射，这种方式一步到位，语义明确，且没有额外的对象分配。

对比其他单元素创建方式

最后，我们通过对比来看看它的优势。下面是一种不推荐的手动方式：

Map m = new HashMap<>();
m.put("name", "Alice");
m = Collections.unmodifiableMap(m); // 多余两步，且有额外对象开销

这种方式不仅步骤繁琐，还创建了多余的 HashMap 实例。而推荐的做法则简洁高效得多：

Map m = Collections.singletonMap("name", "Alice");

一句话，意图清晰，性能更优，这才是关键所在。在需要单一、固定映射的场景下，Collections.singletonMap() 无疑是首选工具。