Collections.singletonMap()返回不可变Map，所有修改操作（如put、remove）均抛UnsupportedOperationException；它接受null键值，而Java 9+的Map.of()禁止null，且二者实现与序列化特性不同。
为什么 Collections.singletonMap() 返回的 Map 看似可变却实际抛出异常
它返回的是一个不可变视图，底层没有存储结构，所有修改操作（如 put()、remove()、clear()）都会直接抛出 UnsupportedOperationException。这不是“懒加载报错”，而是类设计上就禁用了写操作——比如 singletonMap 的内部实现类重写了全部 mutator 方法并统一 throw 异常。
常见误用场景：拿到返回值后尝试 map.put("newKey", "newValue")，结果运行时崩在这一行，且 IDE 不会提前警告。
- 它不继承自
AbstractMap，而是一个独立私有静态类，连entrySet()返回的也是只读集合 - 键和值在构造时就被强引用捕获，后续无法被 GC（除非整个 map 被丢弃）
- 线程安全：由于不可变，天然线程安全，但注意——如果键或值对象本身可变（如传入一个
ArrayList），那外部仍可修改其内容
Collections.singletonMap() 和 Map.of() 在 Java 9+ 的关键区别
Java 9 引入了 Map.of()，它也返回不可变 Map，但行为和限制不同。两者不是简单替代关系。
-
Collections.singletonMap(k, v)接受null键或值（只要类型允许），而Map.of(k, v)明确禁止null——传入会立即抛NullPointerException -
Map.of()返回的实例是紧凑的、高度优化的实现（例如只存两个字段），序列化体积更小；singletonMap则保留了传统 Map 接口的完整委托结构 - 兼容性：若项目需支持 Java 8，只能用
singletonMap；Java 9+ 优先选Map.of()，除非你明确需要容忍null
示例对比：
立即学习“Java免费学习笔记（深入）”；
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
Map<String, Integer> m1 = Collections.singletonMap("a", 1); // OK
Map<String, Integer> m2 = Collections.singletonMap(null, 1); // OK（键为 null）
Map<String, Integer> m3 = Map.of("a", 1); // OK
Map<String, Integer> m4 = Map.of(null, 1); // 抛 NPE
什么时候不该用 singletonMap()，哪怕只塞一对数据
它适合「临时、轻量、明确只读」的场景，比如作为方法参数传递默认配置、构建测试桩返回值。但以下情况应避开：
- 需要频繁复用同一 key-value 对：每次调用都新建对象，不如定义
static final Map常量（用singletonMap初始化一次即可） - 后续可能扩展为多对映射：硬编码
singletonMap会让后期改造成HashMap或Map.ofEntries()时逻辑割裂 - 键或值是计算代价高的对象（如大 JSON 字符串、未缓存的数据库查询结果）：因为
singletonMap构造时不校验、不延迟，值会被立即求值并持有
反模式示例：
// ❌ 每次调用都重复解析 JSON 并创建新 map
return Collections.singletonMap("config", parseHeavyJson());
// ✅ 提前计算好，复用不可变引用
private static final Map<String, Object> CONFIG_MAP =
Collections.singletonMap("config", preParsedConfig);
如何安全地将 singletonMap 用于函数式链式调用
它常出现在 Stream 或 Optional 后续处理中，比如 Optional.map() 或 Stream.collect() 的下游合并逻辑。此时要注意空值传播和类型擦除陷阱。
- 若上游可能为
null，别直接Collections.singletonMap(x, y)，先做非空判断，否则null键/值可能引发下游 NPE（尤其在泛型推导失败时） - 与
Collectors.toMap()混用要小心：后者返回可变 map，而singletonMap是不可变的，不能直接作为toMap的 supplier（会编译失败） - 泛型推导失效时加显式类型参数，例如：
Collections.<string list>>singletonMap("tags", tagsList)</string>，避免因类型擦除导致Object泛型污染
典型安全用法：
Optional<String> maybeId = findId();
Map<String, String> result = maybeId
.map(id -> Collections.singletonMap("id", id))
.orElse(Collections.emptyMap()); // 统一返回不可变 map
最易被忽略的一点：它的不可变性是“浅层”的——如果你传入一个可变集合或自定义对象，外部代码仍能通过引用修改其内部状态，这不会影响 map 结构，但会破坏语义一致性。真正需要深不可变时，得配合 unmodifiableXXX 工具或不可变数据结构库。
