Java Stream 转 Map 报 Duplicate key：明确重复键策略

把查询列表转换成 Map 后，Java 抛出 Duplicate key，接口直接变成 500。给 toMap 随手加一个保留第一条的合并函数，虽然可能不再报错，却也可能丢掉有效记录。本篇以 JDK 17 为范围，用设备查询结果说明键冲突的含义，按一对一与一对多关系选择修复，并给出可区分数据策略的验证样本。

一、先确认这个键真的唯一吗

Map 中一个键只对应一个值。Collectors.toMap 的常用两参数形式没有告诉程序遇到重复键该怎么办，因此遇到冲突会抛出异常。错误不是 Stream 无法处理列表，而是输入关系与目标容器约束不一致。

假设设备查询结果包含同一设备的两次借用记录，用设备编号作为 Map 键就会冲突。这可能是正常一对多，也可能是 JOIN 扩行或源数据重复。修复前先回答：每个设备应该只有一条结果，还是本来就有多条？如果回答不清楚，任何合并规则都可能掩盖问题。

不要把“先不报错”当成业务含义。尤其是金额、库存与权限记录，悄悄舍弃一条可能比异常更难发现。

二、用三条数据复现键冲突

下面是独立教学数据，字段只有编号与名称。创建一个重复编号，能让问题在数据库之外复现。这样可以确认冲突发生在集合转换，不必同时排查网络和数据库连接。

record Device(String code, String name) {}

List<Device> devices = List.of(
new Device("E07", "温度计"),
new Device("E08", "计时器"),
new Device("E07", "温度计备用名"));

Map<String, Device> byCode = devices.stream().collect(
Collectors.toMap(Device::code, Function.identity()));

需要导入 List、Map、Function 与 Collectors。预期转换时抛出 IllegalStateException，异常文本会包含键冲突信息；具体文案不应作为稳定接口契约。本篇未执行读者项目，这里给出依据 JDK API 的预期行为。

查看报错键后，回到原列表检查对应记录。不要只看第一条名称相同就认定它们完全等价，还要比较版本、状态与业务归属。生产日志应只记录必要标识的脱敏值，避免把整条用户记录打印出来。

三、确实一对多时使用分组

如果一个设备对应多条借用记录，正确目标应是列表，而不是一个任意代表值。可以用 groupingBy，把每个编号下的全部记录保留下来：

Map<String, List<Device>> grouped = devices.stream().collect(
Collectors.groupingBy(Device::code));

调用方随后按设备编号读取列表，并明确处理零条、一条与多条。不要把分组结果又直接取第零项，否则只是把丢数据的决定移到了下一行代码。返回 API 时也要同步结果模型，前端不能仍按单个对象读取。

若只是给现有唯一列表建立索引，而重复来自数据库 JOIN，优先检查查询关系。比如设备联查附件时，一台设备有两个附件就产生两行；此时可能需要单独查询附件或使用适合的对象映射。使用 DISTINCT 是否正确要看选择字段，不能机械添加。

四、保留首次值必须有业务授权

只有业务明确允许忽略后续同键记录，才使用合并函数。下面演示保留输入中的首次值，并用 LinkedHashMap 保持键首次出现的顺序。它是一个可选策略，不是通用默认修复。

Map<String, Device> firstByCode = devices.stream().collect(
Collectors.toMap(
Device::code,
Function.identity(),
(first, ignored) -> first,
LinkedHashMap::new));

如果列表来自没有 ORDER BY 的数据库查询，“首次”本身可能不稳定。需要稳定结果时，先定义排序依据和并列裁决，再转换。保留最后一条也面临同样问题，不代表最后查到的一定最新。

选择最新版本时可比较业务版本号或更新时间，但时间相同仍需规则。不要用名称字典序冒充最新，也不要在合并函数里顺手调用外部接口或修改共享状态。合并逻辑越小、越确定，越容易测试与复用。

五、验证保留规则有没有丢信息

对唯一键输入，Map 大小应等于列表大小；对重复键输入，分组后所有列表长度之和应等于原始条数；对首次保留策略，E07 应明确对应第一条，而不是备用名。再打乱输入顺序，观察首次策略是否按设计改变，帮助团队理解它依赖顺序。

还要验证空列表、空编号与空记录。示例使用 List.of 不能包含 null，但真实数据库或接口结果仍可能存在空字段，应在进入转换前按业务规则拒绝或单独处理。不同 Map 实现对空键的支持并不一致，不能依赖某次运行没有异常就当作契约。

若列表非常大，先评估是否真的需要内存索引或完整分组。分页查询得到的 Map 只覆盖当前页，不能当作全量设备字典使用。若多个页面共享缓存，还要设计更新与失效，不要把这个局部转换函数直接扩成长期静态全局变量。

六、让异常暴露真实数据问题

对于本应唯一的数据，保留异常往往有价值。可以在服务边界返回稳定的内部错误码，并记录重复来源供排查，而不是让完整堆栈泄漏给前端。修复源数据时按项目的数据迁移流程执行，不能在捕获异常后自动删除重复记录。

团队应在接口文档里标明键的唯一范围：是全局编号，还是组织加编号的组合？若不同实验室允许相同设备编号，应使用真正的唯一标识或组合键。简单拼接字符串时还要避免分隔符碰撞，更稳妥的是定义不可变组合键对象。

完成验收后，测试不只断言“不抛异常”，而应断言结果大小、每个键的内容和被保留的记录。把关系、容器和合并策略对应起来，Duplicate key 就能引导你修正数据模型，而不是加入一段无法解释的去重代码。

合并前后可以记录输入条数、不同键数量和冲突键数量，作为不含业务正文的诊断指标。若升级查询后冲突突然增多，应先检查关联条件和唯一范围，而不是立即更换合并函数。对于需要拒绝重复的接口，测试应保留这个异常分支，防止后续维护者把它误当成可以随意忽略的噪声。

参考资料

• Oracle Java 17：Collectors，toMap 与 groupingBy。
• Oracle Java 17：Map，键与值约束；2026-10-31 核验。