Java Collectors.toMap 遇到重复键如何保留两条数据

用 Java Stream 把订单列表收集成 Map 时，如果两个订单的 userId 相同，直接调用无合并函数的 Collectors.toMap 会在收集阶段抛出 IllegalStateException。如果目标是保留两条甚至更多数据，最清楚的结果类型不是 Map，而是 Map>，优先使用 Collectors.groupingBy；只有业务确实要压成一个值时，才为 toMap 提供明确的合并函数。

重复键为什么会让默认 toMap 失败

Map 的模型是一个键最多对应一个值，所以默认 toMap(keyMapper, valueMapper) 无法替你猜测“保留第一条、最后一条，还是合并字段”。Java API 对相等键的默认处理是抛出 IllegalStateException。这里的相等依据是键的 equals 语义，不是对象地址，也不只限于字符串。

例如两条订单分别是“用户 7 的待支付订单”和“用户 7 的已支付订单”，它们的 userId 都映射成 7。此时异常反而是在提醒你：业务关系是一对多，结果类型需要重新设计。

要保留两条数据，使用 groupingBy 建立列表值

标题里的“保留两条”通常意味着同一个业务键下的所有对象都不能丢。groupingBy 正好把分类函数返回的键映射到一个列表，代码的类型也会把一对多关系表达出来。

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

record Order(long id, String userId, String status) {}

List orders = List.of(
    new Order(101, "u-7", "待支付"),
    new Order(102, "u-7", "已支付"),
    new Order(103, "u-8", "已发货")
);

// 按 userId 分类，同一用户的所有订单都放进对应列表。
Map> ordersByUser = orders.stream()
    .collect(Collectors.groupingBy(Order::userId));

// 这里的结果包含两条 u-7 订单，不会在建立 Map 时丢失其中一条。
List userOrders = ordersByUser.get("u-7");

u-7 -> [Order[id=101, status=待支付], Order[id=102, status=已支付]]
u-8 -> [Order[id=103, status=已发货]]

默认 groupingBy 的值是 List，适合后面继续筛选、排序或逐条处理。如果输入本身是并行流，可以评估 groupingByConcurrent，但它是无序收集器，返回的 Map 和 List 也不应被当成额外的线程安全边界。

只要一个值时，给 toMap 写明合并规则

有些场景并不是保留两条订单，而是每个用户只需要一份摘要。这时仍可以用 toMap，但第三个参数必须明确重复键的处理方式。合并函数接收旧值和新值，返回写回 Map 的结果；选择首条、末条或字段合并，都应该和业务规则一致。

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

// 只保留每个 userId 的一条摘要；这里选择状态更新较新的记录。
Map latestByUser = orders.stream()
    .collect(Collectors.toMap(
        Order::userId,
        order -> order,
        (oldOrder, newOrder) -> newOrder,
        LinkedHashMap::new
    ));

// 如果业务要保留全部对象，不能用“最后一条”替代 groupingBy。
Map> allByUser = orders.stream()
    .collect(Collectors.groupingBy(Order::userId));

这里指定 LinkedHashMap::new 是为了保留结果 Map 的插入顺序；它不等于给并行流增加排序保证。若合并函数返回 null，Map 合并语义可能会移除该键，因此不要把空值当成“随便忽略冲突”的写法。

按业务目标选择结果类型

还要留意空值约束：映射函数返回 null 时，相关收集器可能抛出 NullPointerException。把输入清洗、默认值和重复键策略分开写，排查时会比在一个 lambda 里悄悄覆盖更容易。

相关问题

toMap 的合并函数能不能直接写成 (a, b) -> a？

可以，它表示重复时保留旧值。但只有在输入顺序和“首条有效”规则都可靠时才适合；如果业务要保留全部数据，应改用 groupingBy。

为什么不直接把重复键改成 Map 的复合键？

复合键会把一对多关系拆散，读取某个用户的全部记录还要重新聚合。只有当复合键本身就是稳定业务标识时才这样设计。

并行流中使用 toMap 会自动保证最终顺序吗？

不会。官方文档说明普通 toMap 不是并发收集器，合并分片 Map 可能有额外成本；需要并发语义时，应先确认是否能接受无序结果。

参考资料

• Java SE 25 Collectors API：toMap、groupingBy 与并发收集器的语义。
• Java SE 25 Map API：Map 的唯一键模型与 merge 规则。