Java Collector收集不可变列表

在 Java Stream 中收集列表时，真正需要先确定的不是方法名，而是结果契约：列表之后还要不要修改、输入里是否允许 null、以及是否要和源集合彻底脱离。标题中的“不可变列表”通常对应 Java API 里的 unmodifiable List，也就是不能通过列表的增删改方法改变它；如果列表里的元素本身可变，元素对象仍然可能被修改。

如果你只想把流按原有 encounter order 收集成不能修改的列表，优先写 Collectors.toUnmodifiableList()。如果更看重简洁，并且使用 Java 16 或更高版本，Stream.toList() 也会返回不可修改的列表。两者最容易踩坑的差异是：toUnmodifiableList() 明确拒绝 null，而 Stream.toList() 的 API 契约没有作出同样的禁止说明。

官方资料：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/stream/Collectors.html

Stream API：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/stream/Stream.html

List API：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/util/List.html

先把“不可变列表”说准确

Java 集合文档更常用 unmodifiable 描述“不能通过这个列表对象修改结构”。这和深层不可变不是一回事。下面的列表不能调用 add，但列表里的 Profile 仍可能被修改：

record Profile(String name, String[] roles) {}

List profiles = List.of(
    new Profile("Lin", new String[]{"reader"})
); // 列表结构不可修改，但数组元素仍是可变对象

profiles.get(0).roles()[0] = "editor"; // 元素内部状态可以变化
// profiles.add(new Profile("Mo", new String[]{"writer"})); // 这类结构修改会抛出 UnsupportedOperationException

因此，本文讨论的是收集结果的结构修改边界。若业务要求对象图也不可变，还要让元素类型本身使用不可变字段、复制数组，或者采用专门的不可变值对象。

用 toUnmodifiableList 收集严格结果

Collectors.toUnmodifiableList() 从 Java 10 开始提供。它按流的 encounter order 收集元素，返回不能添加、删除或替换元素的列表；如果流中出现 null，会抛出 NullPointerException。这使它很适合把内部处理结果交给只读调用方。

List tags = rawTags.stream()
    .filter(Objects::nonNull) // 先排除空值，避免严格 Collector 在终结阶段失败
    .map(String::trim) // 统一去除首尾空白，保留流的 encounter order
    .filter(tag -> !tag.isEmpty()) // 丢掉清洗后的空标签
    .collect(Collectors.toUnmodifiableList()); // 返回结构不可修改的 List

这里的过滤不是为了“让 Collector 更安全”而机械添加的，而是业务决策：如果 null 代表坏数据，可以提前丢弃；如果 null 代表“未知”，则应该先转换成明确的占位对象或 Optional，不要让它在终结操作中突然失败。

Stream.toList 为什么更短

Java 16 起可以直接调用 Stream.toList()：

List visibleNames = users.stream()
    .filter(User::visible) // 只保留当前调用方可见的用户
    .map(User::displayName) // 把用户对象映射成展示名称
    .toList(); // Java 16+：得到不可修改的 List

它的优势是表达清楚：这是 Stream 的终结操作，结果不能通过列表方法修改，而且没有要求你显式写一个 Collector。不要把它和 Collectors.toList() 当作同一个方法的缩写：

如果业务允许 null，又希望写出 Java 16+ 的短代码，Stream.toList() 比 toUnmodifiableList() 更贴近这个需求。但不要仅凭某个 JDK 实现的内部类或当前测试结果推断所有实现细节；代码应该依赖 API 契约。

不要用 Collectors.toList 猜测可修改性

Collectors.toList() 的文档不保证返回列表的类型、可修改性、可序列化性或线程安全性。很多环境里它确实得到可修改的列表，但把“通常如此”写成接口承诺，会让后续替换实现或升级 JDK 时留下隐患。

List editable = source.stream()
    .map(String::trim) // 先完成流内转换
    .collect(Collectors.toCollection(ArrayList::new)); // 显式声明结果必须是可修改 ArrayList

editable.add("manual-entry"); // 这里的追加操作属于业务需要，而不是实现碰巧支持

如果确实需要可修改列表，使用 Collectors.toCollection(ArrayList::new) 把意图写进代码；如果只需要只读结果，就用 toUnmodifiableList() 或 toList()，不要先收集到可变列表再靠约定不去修改。

已有集合要用 List.copyOf 做快照

Collector 解决的是“流如何结束”，而 List.copyOf 解决的是“已有 Collection 如何固定下来”。它按源集合的迭代顺序创建不可修改列表，源集合之后的增删不会反映到返回结果中，并且源集合为 null 或含有 null 元素时会抛出 NullPointerException。

List mutableBuffer = new ArrayList();
mutableBuffer.add("alpha"); // 模拟持续收集阶段
mutableBuffer.add("beta");

List snapshot = List.copyOf(mutableBuffer); // 在交付边界创建不可修改快照
mutableBuffer.add("gamma"); // 后续修改只影响源集合
// snapshot.add("delta"); // 快照结构不可修改，会抛出 UnsupportedOperationException

这也是区分“视图”和“快照”的地方。Collections.unmodifiableList(mutableBuffer) 是不可修改视图，调用方不能通过视图修改结构，但源列表的后续变化仍会被观察到；List.copyOf 的结果则不再跟随可变源集合。

Java 8 兼容代码怎么写

如果项目仍停留在 Java 8，没有 Stream.toList() 和 Collectors.toUnmodifiableList()，可以用 collectingAndThen 加上不可修改包装：

List names = source.stream()
    .map(String::trim) // 保持 Java 8 可用的流式清洗
    .collect(Collectors.collectingAndThen(
        Collectors.toList(), // 先得到内部临时列表
        Collections::unmodifiableList // 再把结果包装成不可修改视图
    ));

这个兼容写法不会自动拒绝 null，而且语义是“对内部列表做不可修改包装”。如果要同时拒绝空值，应在收集前显式过滤或校验。升级到 Java 10+ 后，再根据项目的 null 约束改成 toUnmodifiableList()；升级到 Java 16+ 且接受其契约时，可改成 toList()。

按这张清单做最终选择

1. 结果还要增删改：用 Collectors.toCollection(ArrayList::new)，把可修改性写明。
2. 结果只读且拒绝 null：用 Collectors.toUnmodifiableList()。
3. Java 16+、想要最短的流终结写法：用 Stream.toList()，不要额外假设实现类型。
4. 已有集合需要和源集合脱离：用 List.copyOf，并先决定如何处理 null。
5. 元素对象本身也不能变：只选择不可修改列表还不够，元素类型也要设计成不可变值对象。

常见问题

toUnmodifiableList() 和 Stream.toList() 可以互换吗？

在“不修改列表、保留流顺序”的主路径上很接近，但不能无条件互换。前者明确拒绝 null，后者没有同样的 API 禁止说明；同时前者是 Collector，后者是 Stream 的终结操作。

不可修改列表等于深度不可变吗？

不等于。列表结构不能被修改，但其中元素若是可变对象，元素内部状态仍可能变化。需要深度不可变时，要从元素类型和内部引用的设计一起处理。

为什么不用 Collectors.toList() 再约定不修改？

因为“调用方目前不修改”不是 API 契约。若结果必须只读，直接选择明确的不可修改返回方式；若必须可改，则显式指定 ArrayList 等实现。