Java SequencedMap 如何统一首尾键值操作：firstEntry、lastEntry 与倒序视图

如果一个 Java 服务要保留最近访问顺序，代码里常会出现“取第一个键”“取最后一个键”“从队头移除”几套不同写法。Java 21 的 SequencedMap 把这些操作收拢到同一个接口：firstEntry()、lastEntry()、putFirst()、putLast() 和 reversed() 都直接表达顺序意图。

使用 Java 21 或更高版本时，优先把有明确遇见顺序的 LinkedHashMap 视为 SequencedMap；取首尾元素用 firstEntry() / lastEntry()，反向读取用 reversed()，不要再手写迭代器定位。

旧版代码为什么总要绕一圈找首尾键值

在 Java 17 项目里，Map 只承诺键值映射，不承诺一个能被统一操作的“首尾”概念。即便底层使用 LinkedHashMap，取第一个元素通常要拿到 entrySet().iterator()，取最后一个元素则要遍历到末尾，删除首尾元素还要另外写 iterator.remove() 或先取键再调用 remove()。

这些写法不一定错，问题是顺序语义散落在迭代器细节里。换成 Java 21 后，先把变量声明为 SequencedMap，调用方看到的就是“首项、末项、倒序视图”，代码边界更清楚。

Java 21 的 SequencedMap 到底增加了什么

SequencedMap 继承 Map，但额外要求实现提供稳定的遇见顺序，并支持两端操作和可逆视图。Oracle 的 Java SE 21 API 将 LinkedHashMap、TreeMap 等列为已知实现或子接口体系中的成员，实际选型仍要看你需要插入顺序还是排序顺序。

下面的例子选择 LinkedHashMap，因为它最容易观察插入顺序：

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

public class SequencedMapDemo {
    public static void main(String[] args) {
        SequencedMap scores = new LinkedHashMap();
        scores.put("alice", 91);
        scores.put("bob", 86);
        scores.put("chen", 95);

        Map.Entry first = scores.firstEntry();
        Map.Entry last = scores.lastEntry();
        System.out.println(first.getKey() + "=" + first.getValue());
        System.out.println(last.getKey() + "=" + last.getValue());
    }
}

运行后，firstEntry() 对应 alice=91，lastEntry() 对应 chen=95。这里的“首”和“尾”来自 LinkedHashMap 的插入顺序，不是按分数大小排序。

空 Map 要先判断再读取 Entry

firstEntry() 和 lastEntry() 对空 Map 返回 null。不要在没有判断的情况下直接调用 getKey()；实际业务里可以把取首尾封装为返回 Optional，或者保留明确的空队列分支：

Map.Entry first = scores.firstEntry();
if (first == null) {
    System.out.println("没有可处理的记录");
} else {
    System.out.println("先处理 " + first.getKey());
}

用首尾方法替换手写迭代器

如果目标是把一条最早进入队列的记录移走，Java 21 可以直接使用 pollFirstEntry()；如果只想查看，不要误用会改变集合的操作。对应关系可以按下面的意图理解：

SequencedMap queue = new LinkedHashMap();
queue.put("task-101", 1);
queue.put("task-102", 1);

Map.Entry oldest = queue.pollFirstEntry();
Map.Entry newest = queue.lastEntry();
System.out.println("removed=" + oldest.getKey());
System.out.println("still-last=" + newest.getKey());

pollFirstEntry() 会返回并移除首项，lastEntry() 只是读取末项。若队列可能为空，oldest 仍然要判空；方法名相似不代表它们具有相同的副作用。

reversed() 如何读取最新项而不复制 Map

很多“最近访问”场景只想从最新记录开始遍历。reversed() 返回一个倒序视图，下面的 sequencedEntrySet() 会从原 Map 的末项走向首项：

SequencedMap recent = new LinkedHashMap();
recent.put("login", 1);
recent.put("search", 2);
recent.put("checkout", 3);

for (Map.Entry entry
        : recent.reversed().sequencedEntrySet()) {
    System.out.println(entry.getKey() + "=" + entry.getValue());
}

输出顺序是 checkout、search、login。视图仍然关联底层 Map，不应把它当成独立快照；如果另一段代码修改了原 Map，遍历期间的并发修改规则仍要遵守。

putFirst 与 putLast 是位置操作，不是普通更新

当键已经存在时，putFirst() 和 putLast() 可以表达“把这个映射移动到哪一端”的意图；当键不存在时，它们则是在指定端插入。示例中的节点顺序变化很直观：

SequencedMap events = new LinkedHashMap();
events.put("open", 1);
events.put("edit", 2);
events.put("save", 3);
events.putFirst("save", 30);

System.out.println(events.sequencedKeySet());
// [save, open, edit]

值更新为 30 的同时，save 被放到了首端。若业务只想覆盖值而不改变顺序，就应使用普通的 put()，不要误把 putFirst() 当作语法更长的更新方法。

从 Java 17 迁移时要守住哪些边界

SequencedMap 的接口和这些方法从 Java 21 才可用。项目仍以 Java 17 编译时，直接引用它会在编译阶段失败；兼容旧版本不能靠运行时捕获异常解决。需要同时支持 Java 17 和 Java 21 时，可以继续封装旧版迭代器实现，或者把首尾能力放进一个项目自己的适配器中。

另外，接口只描述遇见顺序，不替你选择顺序来源。LinkedHashMap 适合插入顺序，TreeMap 的首尾则受比较器支配。迁移时先确认“首项”在业务里究竟代表最早插入、最小键，还是最近访问，否则 API 写得再漂亮也会把业务语义带偏。

一份可落地的采用检查

1. 确认编译和运行环境至少是 Java 21，并检查 CI 使用的 JDK 版本。
2. 确认底层 Map 的顺序来源，再决定声明为 SequencedMap 还是保留更具体的实现类型。
3. 把首尾读取改为 firstEntry() / lastEntry()，同时补上空 Map 分支。
4. 需要从最新到最早读取时使用 reversed()，不要先复制再反转。
5. 区分 put() 和 putFirst() / putLast() 的顺序副作用，并为迁移补一条顺序断言。

相关问题

SequencedMap 能保证所有 Map 都有插入顺序吗？

不能。它要求有明确的遇见顺序，但顺序可能来自插入规则，也可能来自排序规则。要结合具体实现判断。

reversed() 会复制一份新的 Map 吗？

它返回倒序视图，不应按独立快照理解。需要跨线程长期保存时，仍要自行设计快照或同步策略。

空 Map 调用 lastEntry() 会抛异常吗？

不会直接抛异常，返回值是 null；真正容易出错的是后续未判空就访问 Entry。

总结

Java 21 的 SequencedMap 解决的是顺序 Map 的表达问题：firstEntry() 和 lastEntry() 负责两端读取，pollFirstEntry() 负责带移除的消费，reversed() 负责反向视图，putFirst() 与 putLast() 负责位置更新。迁移前只需把 JDK 版本、顺序来源、空值处理和位置副作用逐项核对，就能避免把“顺序 API”换成另一种隐蔽 bug。