Java Stream toMap 怎么生成不可变 Map 并保留明确错误边界

在把 Stream 收集成 Map 时，真正需要先定下来的不是语法，而是三个边界：键是否唯一、重复键怎样处理、结果是否允许被修改。键唯一且需要防止调用方改写时，直接使用 Collectors.toUnmodifiableMap；可能重复时传入合并函数；并行流若更看重吞吐，可先用 toConcurrentMap，最后用 Map.copyOf 做不可变快照。

最小可靠选择是：唯一键用两参数 toUnmodifiableMap，重复键用三参数变体并写清策略，分组结果再冻结外层 Map；不要把“不可修改”和“并发收集”混成一个概念。

先把不可变 Map 的错误边界定清楚

toUnmodifiableMap(keyMapper, valueMapper) 适合“一个键只能对应一个值”的数据。它返回的 Map 不能通过 put、remove 等操作修改，且映射函数不能产生 null。更重要的是，重复键不是被静默覆盖，而是在收集时以 IllegalStateException 暴露出来。

import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

record Order(String id, String status) {}

List orders = List.of(
    new Order("A-100", "PAID"),
    new Order("A-101", "SHIPPED")
);

// 订单 id 必须唯一，结果交给调用方后不允许改写
Map statusById = orders.stream()
    .collect(Collectors.toUnmodifiableMap(
        Order::id,
        Order::status
    ));

// statusById.put("A-102", "PAID"); // 会抛 UnsupportedOperationException

这里的“不可变”是结果 Map 的修改入口被禁止，并不等于 Order 或其他值对象本身深度不可变。若值对象仍可变，调用方依旧可能通过引用改变内部状态。

重复键不要靠“最后一次覆盖”蒙混过去

业务上允许重复时，使用三参数变体。合并函数的两个参数分别代表同一键对应的已有值和新值，返回哪个值就是你的数据策略。比如订单状态字典通常不能无声丢数据，可以把冲突改成带键的业务异常：

import java.util.function.Function;

Map byId = orders.stream()
    .collect(Collectors.toUnmodifiableMap(
        Order::id,
        Function.identity(),
        (oldOrder, newOrder) -> {
            // 把重复键变成可定位的业务错误，不静默覆盖
            throw new IllegalArgumentException(
                "重复订单 id: " + oldOrder.id());
        }
    ));

如果产品规则明确要求“第一条优先”，可以返回 oldOrder；要求“最新记录优先”才返回 newOrder。不要只因为编译器要求合并函数，就随手写 (a, b) -> b。这会把数据质量问题变成难以追溯的覆盖。

分组结果要同时冻结内层和外层

分组通常得到 Map>。下游收集器可以先把每个分组的 List 做成不可修改，再用 Map.copyOf 冻结外层 Map：

Map> codesByTeam = orders.stream()
    .collect(Collectors.groupingBy(
        order -> order.status(),
        Collectors.mapping(
            Order::id,
            Collectors.toUnmodifiableList()
        )
    ));

// groupingBy 返回的外层 Map 仍需单独冻结
Map> immutableGroups = Map.copyOf(codesByTeam);

这段代码的边界很清楚：每个分组的 List 不能改，外层键集合也不能改。Map.copyOf 会拒绝 null 键和值；如果分组逻辑可能产出 null，先在进入收集器前完成清洗或把 null 转换为明确的业务标识。

并行流要先决定顺序还是吞吐

普通 toMap 是非并发 Collector。并行收集时，各分片结果需要在合并器中合并，键很多时这一步可能成为成本。若不要求 Map 的遇到顺序，可以考虑 toConcurrentMap；它返回并发 Map，但不等于最终结果不可修改，也不保证遍历顺序。

import java.util.concurrent.ConcurrentMap;

ConcurrentMap concurrentById = orders.parallelStream()
    .collect(Collectors.toConcurrentMap(
        Order::id,
        Function.identity(),
        (oldOrder, newOrder) -> oldOrder
    ));

// 发布只读快照，避免把可变并发容器继续向外暴露
Map snapshot = Map.copyOf(concurrentById);

如果调用方依赖稳定的遍历顺序，别为了并行而直接换成 toConcurrentMap。先评估数据规模和顺序要求；很多中小集合用普通 Stream 收集后冻结更容易维护。并行只解决一部分计算成本，不能替代明确的重复键策略。

相关问题

toMap 和 toUnmodifiableMap 最大区别是什么？

toMap 的结果不承诺具体 Map 类型、可变性或线程安全；toUnmodifiableMap 明确返回不可修改 Map，并拒绝 null 键和值。

为什么加了合并函数仍可能出现异常？

合并函数只负责重复键的值决策；映射函数为 null、合并函数本身为 null，或合并函数主动抛出业务异常，仍会失败。

Map.copyOf 能让嵌套对象全部深度不可变吗？

不能。它只冻结外层 Map；嵌套 List 要用 toUnmodifiableList 或其他不可修改包装，值对象也要自行设计为不可变。

落地时可以按“唯一键直接收集、重复键显式合并、分组内外两层冻结、并行先确认顺序”检查。这样得到的 Map 不只是不能修改，失败原因和并发语义也能被调用方准确理解。