Java SequencedMap 怎么操作首尾键值

Java 21 引入的 SequencedMap 把“有顺序的 Map”统一成了一个接口：可以直接拿到首个或最后一个键值对，也可以从两端移除、把键放到首端或尾端。实际开发中通常用 LinkedHashMap 承载数据，再用 SequencedMap 引用它；这里的首尾依据 encounter order（遍历顺序），不是比较键的大小。

用 LinkedHashMap 先确定首尾顺序

SequencedMap 只对“顺序明确”的映射有意义。下面让 LinkedHashMap 记录三个任务的插入顺序，再用接口类型调用统一 API。Java 21 之前的编译环境没有这个接口，项目需要先确认运行时和编译器版本。

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

public class SequencedMapDemo {
    public static void main(String[] args) {
        // LinkedHashMap 默认按插入顺序维护 encounter order
        SequencedMap tasks = new LinkedHashMap();
        tasks.put("parse", 10);
        tasks.put("validate", 20);
        tasks.put("publish", 30);

        // 遍历顺序是 parse -> validate -> publish
        tasks.forEach((name, cost) -> System.out.println(name + "=" + cost));
    }
}

如果业务使用的是 TreeMap，首尾通常由排序规则决定；如果使用普通 HashMap，不要把当前遍历结果当成稳定的首尾语义。先确认实现类提供的顺序，再选择后面的 API。

用 firstEntry 和 lastEntry 读取两端键值

只查看首尾时，优先使用 firstEntry() 与 lastEntry()，它们返回 Map.Entry 快照。映射为空时两个方法都返回 null，因此不要直接链式调用 getKey()。

import java.util.Map;

// 读取首尾时统一处理空映射，避免空指针异常
Map.Entry first = tasks.firstEntry();
Map.Entry last = tasks.lastEntry();
if (first == null || last == null) {
    System.out.println("映射为空，没有首尾键值");
} else {
    // firstEntry/lastEntry 的返回值适合做一次性读取
    System.out.println("首端=" + first.getKey() + ":" + first.getValue());
    System.out.println("尾端=" + last.getKey() + ":" + last.getValue());
}

这两个返回值不能用 setValue() 反向修改底层映射；如果目的是改值，直接对映射调用 put 或 replace，这样意图更清楚。

把读取、删除和位置调整分成三种操作

首尾 API 的差别在于是否改变集合。读取用 firstEntry/lastEntry，消费用 pollFirstEntry/pollLastEntry，调整位置用 putFirst/putLast。后两组属于可选操作，具体实现不支持时会抛出 UnsupportedOperationException。

// poll 会移除并返回首端映射，适合逐项消费任务队列
Map.Entry next = tasks.pollFirstEntry();
if (next != null) {
    System.out.println("已消费=" + next.getKey());
}

// 把已有键放到尾端，并同时更新它的值
tasks.putLast("validate", 25);

// 把新键放到首端；实现类不支持时需要在边界处处理异常
try {
    tasks.putFirst("prepare", 5);
} catch (UnsupportedOperationException ex) {
    System.out.println("当前映射实现不支持首端插入");
}

poll 返回的是被移除项，适合“取出后处理”；它和 firstEntry 的核心区别不是返回类型，而是是否改变映射。生产代码还应结合实现类文档确认可选操作，而不是只看接口默认方法。

reversed() 是同一映射的反向视图

需要从最新项向最早项遍历时，不必复制一份 Map。reversed() 将 encounter order 反过来，因此反向视图的首端就是原映射的尾端，reversed().firstEntry() 等价于从原映射取最后一个映射。

// reversed 返回反向视图，不额外复制所有键值
SequencedMap newestFirst = tasks.reversed();
newestFirst.forEach((name, cost) ->
        System.out.println("倒序=" + name + ":" + cost));

// 反向视图的首端对应原映射的尾端
Map.Entry newest = newestFirst.firstEntry();
if (newest != null) {
    System.out.println("最新任务=" + newest.getKey());
}

反向视图是否支持写入，以及写入是否透传到底层映射，取决于实现类；不要把它当成独立快照长期保存。需要稳定副本时，再显式构造新的 LinkedHashMap 并按目标顺序复制。

常见问题

SequencedMap 的首端是按 key 排序吗？

不是。它依据实现类定义的 encounter order；LinkedHashMap 常见的是插入顺序，TreeMap 则受排序规则影响。

firstEntry() 返回的 Entry 能修改原 Map 吗？

不能依赖这种行为。接口明确把这些方法的结果定义为映射快照，修改应回到底层 Map 调用 put 或 replace。

什么时候应该用 pollFirstEntry()？

当业务确实要从首端取出并删除一项时使用，例如按顺序消费任务；只想查看下一项时使用 firstEntry()。

记住一个判断顺序：先确认实现类和 encounter order，再按“读、删、调位、反向查看”选择方法。这样既能写出简洁的首尾操作，也能避开空映射、可选操作和视图写入的边界。