Java Map.copyOf 怎样构造不可变映射快照

我在整理一段会被多个线程读取的配置代码时，第一次把 Collections.unmodifiableMap 换成 Map.copyOf，最明显的变化不是写法更短，而是“读者拿到的到底是哪一种对象”变得更清楚了：前者是对原 Map 的只读视图，后者返回包含当前条目的不可变 Map。只要源 Map 没有 null 键或 null 值，Map.copyOf 就适合把一批已经准备好的映射固定下来。

官方文档：https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Map.html#copyOf(java.util.Map)

如果目标是“读取方不能改、源 Map 后续变化也不影响结果”，直接使用 Map.copyOf(source)。它拒绝 null 键和值；但它只是容器层面的不可变快照，键和值对象本身仍然可能是可变的。

Map.copyOf 解决的不是“禁止别人调用 put”这么简单

Map.copyOf 是 Java 集合工厂方法，返回一个包含源 Map 条目的不可变 Map。返回对象的修改方法会抛出 UnsupportedOperationException，并且源 Map 之后再增删条目，返回对象不会跟着变化。

这和只读视图的差异很关键。视图仍然观察同一个底层 Map；快照则把“构造时的映射关系”交给新的不可变容器保存。下面这张结构说明图只表达对象与语义的静态关系，不是运行截图。

从可变 Map 构造一个真正的不可变快照

最小写法是把源 Map 作为参数传给 Map.copyOf。示例里的 source 继续可以修改，但 snapshot 保存的是调用时的条目集合。

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

public class MapCopyOfDemo {
    public static void main(String[] args) {
        Map source = new HashMap<>();
        source.put("timeout", 30);
        source.put("retries", 2);

        // 把当前条目保存为不可变映射，供读取方共享。
        Map snapshot = Map.copyOf(source);

        // 源 Map 后续变化不会回写到 snapshot。
        source.put("timeout", 60);

        System.out.println(snapshot.get("timeout")); // 仍表示构造快照时的 30
        System.out.println(source.get("timeout"));   // 源 Map 已经变成 60
    }
}

这里要把“快照”理解成容器条目的固定集合，而不是递归复制对象图。若 value 是一个可变的 List 或自定义对象，Map.copyOf 不会自动复制这个 value；它只约束 Map 自身的增删改。

和 Collections.unmodifiableMap 的差别在哪里

旧代码里常见的写法是 Collections.unmodifiableMap(source)。它返回一个包装视图，读取方不能直接通过这个视图修改 Map，但源 Map 的变化仍然会被视图看到。需要“发布后不再变化”的配置、路由表或元数据时，这个语义可能不够。

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

public class MapViewCompare {
    public static void main(String[] args) {
        Map source = new HashMap<>();
        source.put("mode", "safe");

        // 只读视图仍然观察 source 的后续变化。
        Map view = Collections.unmodifiableMap(source);
        // Map.copyOf 保存调用时的条目，不跟随 source 增删改。
        Map snapshot = Map.copyOf(source);

        source.put("mode", "fast");
        System.out.println(view.get("mode"));     // 视图看到 fast
        System.out.println(snapshot.get("mode")); // 快照仍是 safe
    }
}

因此迁移时不能只看返回类型都写成 Map：如果调用方需要实时观察源数据，保留视图；如果调用方需要稳定读取边界，使用快照。

null 键和值要在构造前处理

Map.copyOf 的输入 Map 本身不能是 null，也不能含有 null key 或 null value。遇到这些情况会抛出 NullPointerException，这不是把 null 转成空字符串或忽略条目的过程。

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

public class MapCopyOfNull {
    static Map freeze(Map source) {
        // 先明确业务是否允许缺失值，再决定过滤还是补默认值。
        if (source.containsKey("region") && source.get("region") == null) {
            throw new IllegalArgumentException("region 不能为 null"); // 让业务错误更容易定位
        }
        // Map.copyOf 负责最后的不可变约束，不负责业务默认值推导。
        return Map.copyOf(source);
    }

    public static void main(String[] args) {
        Map source = new HashMap<>();
        source.put("region", "cn");
        Map snapshot = freeze(source);
        System.out.println(snapshot); // 这里的 Map 可读但不可修改
    }
}

如果业务允许“没有值”，可以在构造快照前过滤无效条目，或者把缺失状态改成明确的非 null 值。不要为了绕过异常把所有 null 静默丢弃，因为这可能改变配置含义。

不可变不等于深复制，迭代顺序也不要猜

Map.copyOf 的不可变性只覆盖 Map 这个容器。下面的键和值如果是可变对象，内部状态仍可能变化；要得到真正的业务快照，必须在值类型层面设计不可变对象，或者显式复制值。

另一个容易忽略的点是迭代顺序。Map.of、Map.ofEntries 和 Map.copyOf 创建的不可变 Map 不承诺固定迭代顺序。如果页面、签名或测试依赖顺序，就先选择有明确顺序语义的结构，再决定如何冻结。

import java.util.LinkedHashMap;
import java.util.Map;

public class MapCopyOfOrder {
    public static void main(String[] args) {
        Map orderedSource = new LinkedHashMap<>();
        orderedSource.put("first", 1);
        orderedSource.put("second", 2);

        // 复制条目并锁定容器，不把迭代顺序当成 Map.copyOf 的保证。
        Map snapshot = Map.copyOf(orderedSource);
        snapshot.forEach((key, value) -> System.out.println(key + "=" + value));
    }
}

若顺序是协议的一部分，应把顺序要求写入类型和接口设计，而不是依赖某次运行中观察到的输出顺序。

我的迁移判断：什么时候用 Map.copyOf

我现在通常把 Map.copyOf 放在配置组装的最后一层：先完成校验、默认值和必要的值复制，最后再冻结容器。这样异常发生在边界处，调用方也能从类型和命名上看出“这是一份发布后的快照”。

结语

Java Map.copyOf 的核心价值是把“当前映射关系”变成一个不可变、拒绝 null 的读取对象。它和只读视图的区别在于是否跟随源 Map 变化；它和深复制的区别在于是否复制键和值对象；它和有序集合的区别在于是否承诺迭代顺序。把这三个边界分开，迁移时就不会只因为写法更短而改变配置语义。

相关问题

• Map.copyOf 会复制 value 对象吗？不会，它主要固定 Map 的条目关系；可变 value 仍需业务层显式复制或改用不可变类型。
• Map.copyOf 为什么会抛 NullPointerException？因为输入 Map、键和值都必须非 null。
• Map.copyOf 和 unmodifiableMap 怎么选？需要稳定快照选 Map.copyOf，需要实时只读视图选 unmodifiableMap。
• Map.copyOf 能保证遍历顺序吗？不能。需要顺序时，应使用明确承诺顺序的结构并把它写入设计。