Java中Map.Entry.setValue()在不可变Map视图中会抛出UnsupportedOperationException，这是设计使然而非bug，因不可变Map的Entry是只读代理，setValue被转发到底层不支持修改的实现。
Java 中 Map.Entry.setValue() 在不可变 Map 视图（如 Collections.unmodifiableMap() 返回的 Map）中调用时，会抛出 UnsupportedOperationException。这不是 bug，而是设计使然 —— 不可变视图禁止任何结构性或值级修改。
为什么不可变 Map 的 Entry.setValue 会失败
不可变 Map（如 Collections.unmodifiableMap(map)、Map.of()、Map.copyOf()）返回的 Entry 对象是原始 Map Entry 的包装或代理。虽然 Entry.getKey() 和 Entry.getValue() 可正常调用，但 setValue() 会被转发到底层实现。而底层实现本身不支持修改（例如 UnmodifiableMap.UnmodifiableMapEntry 直接抛异常），因为这会破坏“不可变”的契约。
- 不可变 Map 的所有操作（包括迭代出的 Entry）都只读，
setValue属于写操作，被显式拒绝 - 即使你用
entrySet().iterator().next()获取到一个 Entry，它仍是不可变视图的一部分，不是独立副本 -
Map.ofEntries(Map.Entry...)创建的 Map 同样如此，其 Entry 也不支持 setValue
常见误用场景与识别方式
以下代码看似合理，实则运行时失败：
Map<String, Integer> base = new HashMap<>();
base.put("a", 1);
Map<String, Integer> unmod = Collections.unmodifiableMap(base);
for (Map.Entry<String, Integer> e : unmod.entrySet()) {
e.setValue(99); // ← 抛出 UnsupportedOperationException
}
排查时注意：
Java Maven Common
下载
Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。
立即学习“Java免费学习笔记（深入）”；
- 堆栈跟踪中出现
UnsupportedOperationException，且异常发生在UnmodifiableMapEntry.setValue或类似类中 - Map 实例类型为
UnmodifiableMap、ImmutableCollections$MapN（Map.of）、或Map$Values等内部不可变类 - 调用链中未显式创建新 Map，却尝试修改 Entry 值，容易误以为“只是改个值而已”
安全替代方案
若确实需要修改键值对，必须基于可变 Map 操作：
-
先转为可变副本再操作：用
new HashMap(unmod)构造新 Map，再遍历修改 -
避免直接修改 Entry：改用
map.put(key, newValue)，前提是 map 本身可变 -
函数式处理：用
unmod.entrySet().stream().collect(Collectors.toMap(...))构建新 Map -
检查是否可变：可通过
map instanceof java.util.HashMap等判断（不推荐强依赖实现类，仅用于调试）
如何提前规避这类问题
开发阶段即可降低风险：
- 明确变量命名，如
configReadOnly、defaultsImmutable，提醒自己不可修改 - 在返回不可变 Map 的 API 文档中注明 “entries are read-only”
- 单元测试覆盖对 Entry 的操作，尤其当方法接收通用
Map参数时 - 使用静态分析工具（如 ErrorProne）启用
ImmutableModification检查
