Java 中创建不可变嵌套 Map 方法

本文介绍在 Java 中正确初始化嵌套不可变 Map 的标准方法：使用 JDK 9+ 原生 Map.of() 构建外层与内层不可变映射，避免 Guava ImmutableMap.builder() 的类型不匹配与实例化错误。

本文介绍在 Java 中正确初始化嵌套不可变 Map 的标准方法：使用 JDK 9+ 原生 `Map.of()` 构建外层与内层不可变映射，避免 Guava `ImmutableMap.builder()` 的类型不匹配与实例化错误。

在 Java 开发中，构建多层嵌套的不可变数据结构是常见需求，尤其在配置、错误码映射或统计指标定义等场景中。一个典型模式是：外层 Map<String, ?> 的值本身也是一个不可变映射（如 Map<String, String[]>），且整个结构需在声明时一次性初始化、运行时不可修改。

关键误区澄清：

• ImmutableMap（来自 Guava）是抽象类，不能直接 new 或通过 put(...) 静态调用（如 ImmutableMap.put(...) 不存在）；
• ImmutableMap.builder() 要求泛型严格匹配，而 put(key, value) 只接受单个键值对，无法链式添加多个内层 map；
• 混用 Guava ImmutableMap 和 JDK Map.of() 会导致类型不兼容（例如 Map.of() 返回 Map<K,V>，非 ImmutableMap 子类），但——这恰恰是推荐做法：JDK 原生 Map.of() 已提供轻量、标准、无依赖的不可变语义。

✅ 正确方案：统一使用 JDK 9+ 的 Map.of()（支持最多 10 个键值对）或 Map.ofEntries()（支持任意数量），逐层构造：

private static final Map<String, Map<String, String[]>> Errors = Map.of(
    PppoeAgentStatTypes.RECEIVED.getCounterType(),
        Map.of(
            PppoeAgentCounters.AC_SYSTEM_ERROR.getCounterType(),
                new String[]{PppoeAgentCounters.PADS.getCounterType(), PppoeAgentCounters.PADO.getCounterType()},
            PppoeAgentCounters.SERVICE_NAME_ERROR.getCounterType(),
                new String[]{PppoeAgentCounters.PADS.getCounterType(), PppoeAgentCounters.PADO.getCounterType()}
        ),
    PppoeAgentStatTypes.TRANSMITTED.getCounterType(),  // 第二个外层 key（示例）
        Map.of(
            PppoeAgentCounters.SESSION_TIMEOUT.getCounterType(),
                new String[]{PppoeAgentCounters.PADT.getCounterType()}
        )
);

? 说明：

• 外层 Map.of(...) 返回 Map<String, Map<String, String[]>>，其值为内层 Map.of(...) 构造的不可变映射；
• 所有嵌套 Map 均为 JDK 不可变实现（UnmodifiableMap 包装），任何 put/clear 操作将抛出 UnsupportedOperationException；
• 若条目数超过 10 个，改用 Map.ofEntries() + Map.entry()：

private static final Map<String, Map<String, String[]>> Errors = Map.ofEntries(
    Map.entry(
        PppoeAgentStatTypes.RECEIVED.getCounterType(),
        Map.ofEntries(
            Map.entry(PppoeAgentCounters.AC_SYSTEM_ERROR.getCounterType(),
                new String[]{PppoeAgentCounters.PADS.getCounterType(), PppoeAgentCounters.PADO.getCounterType()}),
            Map.entry(PppoeAgentCounters.SERVICE_NAME_ERROR.getCounterType(),
                new String[]{PppoeAgentCounters.PADS.getCounterType(), PppoeAgentCounters.PADO.getCounterType()})
        )
    ),
    Map.entry(
        PppoeAgentStatTypes.TRANSMITTED.getCounterType(),
        Map.of(PppoeAgentCounters.SESSION_TIMEOUT.getCounterType(),
            new String[]{PppoeAgentCounters.PADT.getCounterType()})
    )
);

⚠️ 注意事项：

• 确保使用 Java 9 或更高版本（Map.of() 自 JDK 9 引入）；
• Map.of() 不允许 null 键或值，若业务需支持 null，应改用 Collections.unmodifiableMap(new HashMap<>(...)) 手动封装（牺牲声明式简洁性）；
• 如项目已深度依赖 Guava，且必须返回 ImmutableMap 类型，可使用 ImmutableMap.copyOf(Map.of(...)) 进行转换，但无实际收益，反而增加开销；
• 建议将常量声明为 static final，并配合 private 封装，确保全局唯一、线程安全、不可篡改。

综上，摒弃 Guava ImmutableMap.builder() 在嵌套场景下的复杂类型推导，拥抱 JDK 原生不可变工厂方法，是更简洁、标准、可维护的实践路径。