Stream toList 不可变怎么配置或排查

把 Java Stream 迁移到 toList() 后，最常见的现象是调用方一执行 add()、remove() 或 set() 就收到 UnsupportedOperationException。这不是少配了某个开关，而是 API 契约本身如此：从 Java 16 开始，Stream.toList() 返回不可修改的 List。需要可变列表时，应在边界处明确选择可变收集方式。

Stream.toList() 的不可变到底是什么意思

Oracle Java SE 21 的 Stream API 明确写出：toList() 将元素收集成 List，如果流存在 encounter order，列表会保留这个顺序；返回值是 unmodifiable，任何修改器方法都会抛出 UnsupportedOperationException。它从 Java 16 开始提供，因此这是一项 API 语义，不是 Spring 或构建工具里的配置项。

“不可变”在这里更准确的理解是“列表结构不可修改”，不是深度冻结。比如列表中的某个自定义对象仍可能被修改，toList() 不会自动复制或冻结元素对象。另一个容易忽略的点是：API 没有像 Collectors.toUnmodifiableList() 那样声明拒绝 null；如果业务要求列表内不能出现 null，应在收集前显式校验。

需要可变 List 时，不要给 toList() 找配置项

如果结果只是返回给控制器、序列化为 JSON 或交给下一个只读环节，直接使用 toList() 更能表达意图。若后续业务确实要追加元素，最小改法是在修改边界复制一份：

import java.util.ArrayList;
import java.util.List;

List names = List.of("Ada", "Linus", "Grace");
List readonly = names.stream()
        .map(String::trim)
        .toList();

// 只有在后续流程需要增删改时才复制为明确的可变列表。
List mutable = new ArrayList(readonly);
mutable.add("Ken"); // 这里允许修改

如果从一开始就确定要得到 ArrayList，可以直接把实现类型写进收集器。这样比依赖 Collectors.toList() 在某个 JDK 中恰好返回可变列表更稳：

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

List mutable = names.stream()
        .filter(name -> !name.isBlank())
        // 显式指定 ArrayList，后续 add/remove 的契约清楚可见。
        .collect(Collectors.toCollection(ArrayList::new));

四种写法的边界可以这样记：

UnsupportedOperationException 怎么定位

先看异常栈中真正执行修改的位置，再回溯这个 List 的创建表达式。重点搜索 add、remove、set、sort、replaceAll 和 clear。如果返回值来自 toList()、List.of()、List.copyOf() 或不可修改包装器，异常通常是预期行为，不是数据为空。

排查时可以按三层判断：

1. 看来源：确认是否在最近的迁移提交中把 collect(Collectors.toList()) 换成了 toList()。
2. 看契约：调用方是只读、需要追加，还是要求稳定的具体实现类型；不要只看变量声明为 List。
3. 看修复位置：在产生结果的地方选择正确收集器，或在确实需要修改的边界做一次 new ArrayList(source)，避免到处捕获异常。

static  List mutableCopy(List source) {
    // 复制元素引用，不负责深拷贝元素对象；调用方应确认这一点。
    return new ArrayList(source);
}

从 Collectors.toList() 迁移前的检查清单

第一，检查编译目标。如果项目仍以 Java 8 或 Java 11 API 编译，Stream.toList() 本身不可用，不能只改源码而忽略 toolchain；此时可继续使用 Collectors.toList()，或用 toCollection(ArrayList::new) 把可变性写清楚。

第二，检查接口边界。若方法返回值会被多个模块共享，默认只读通常更安全；若调用方有增删需求，就把返回类型和构造方式的约定写进方法说明，避免调用者猜测。

第三，检查 null 和元素生命周期。需要拒绝 null 时使用 Collectors.toUnmodifiableList() 或在流中先验证；需要修改元素内部字段时，记住“列表不可修改”和“元素不可变”是两件事。

最后做一次针对性的回归：覆盖空流、单元素、含 null 数据、调用方追加元素以及 Java 编译版本。只要结果契约与调用方需求一致，就不需要为 toList() 额外寻找配置。

相关问题

Stream.toList() 和 Collectors.toUnmodifiableList() 有什么区别？

两者都返回不可修改列表，但 Collectors.toUnmodifiableList() 的 API 明确拒绝 null；Stream.toList() 直接作为 Stream 的终端操作使用，并从 Java 16 起提供。

为什么 Collectors.toList() 有时可以 add，有时不应该依赖？

Oracle 文档没有保证它的实现类型、可变性、可序列化性或线程安全性。需要确定可变性时，请显式复制或使用 toCollection(ArrayList::new)。

参考资料：

• https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/stream/Stream.html
• https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/stream/Collectors.html