自定义Stream源并不是直接实现Stream接口，而是实现Spliterator，再借由StreamSupport完成转换。理解这一点，是把远程分页接口、文件分块读取甚至内存映射数据接入Java Stream的第一步。Spliterator这个名字可以拆成split和iterator，它既要像Iterator一样按顺序产出元素，又要在并行流中把数据源拆成多个不重叠的片段。标准集合如ArrayList之所以能高效并行遍历，就是因为它的Spliterator能够根据数组索引快速对半拆分，而不是复制底层数据。
实现一个自定义Spliterator时，真正需要回答的问题只有三个：数据源从哪里取元素、从哪里拆成两份、以及这份数据源具备哪些可优化特征。下面先通过接口定义把这些问题落到实处。
Spliterator接口的核心契约
自定义Stream源的首要工作是实现Spliterator接口。它和Iterator最明显的区别是多了trySplit方法，但另外三个方法同样影响流的行为。先看接口的几个核心方法。
public interface Spliterator<T> {
boolean tryAdvance(Consumer<? super T> action);
Spliterator<T> trySplit();
long estimateSize();
int characteristics();
}
tryAdvance是单线程遍历的基础。方法接收一个Consumer，每次调用尝试消费一个元素，如果还有元素就执行action并返回true，没有元素则返回false。Stream的forEach、map、filter等操作最终都会反复调用这个方法。对于分页数据源，tryAdvance应尽量只触发一次远程请求并读取一批数据，之后从本地批次逐个返回，避免每个元素都发一次网络调用。
trySplit用于并行。它应当把当前Spliterator负责的区间切成两部分，一部分由当前对象继续负责，另一部分封装成新的Spliterator返回。如果数据已经足够小或无法再拆，就返回null。拆分出来的实例最好与当前对象完全独立，避免共享可变游标。estimateSize返回剩余元素数量的估计值，不要求完全精确，但若声明了特征值SIZED，则该值必须准确。characteristics返回一组标志位，告诉Stream框架这段数据是否有序、是否不可变、是否支持并发修改等。
接口中还有默认方法forEachRemaining，通常不需要覆盖。它内部会循环调用tryAdvance，除非有更高效的批量处理方式。对于按页拉取的场景，默认实现已足够。
实现一个分页拉取的自定义Spliterator
假设有一个远程服务提供分页接口，每页固定返回100条数据，总页数已知。如果把所有页加载到一个ArrayList再调用list.stream()，内存会随着总数据量线性增长。更好的做法是实现一个PagedSpliterator，让流在消费过程中按页拉取数据，并在并行时按页区间拆分。
public class PagedSpliterator<T> implements Spliterator<T> {
private final int pageSize;
private final IntFunction<List<T>> pageFetcher;
private int currentPage;
private int lastPage;
private List<T> currentBatch;
private int batchIndex;
public PagedSpliterator(int pageSize, int firstPage, int lastPage,
IntFunction<List<T>> pageFetcher) {
this.pageSize = pageSize;
this.currentPage = firstPage;
this.lastPage = lastPage;
this.pageFetcher = pageFetcher;
}
@Override
public boolean tryAdvance(Consumer<? super T> action) {
if (currentBatch == null || batchIndex >= currentBatch.size()) {
loadNextPage();
}
if (currentBatch == null || batchIndex >= currentBatch.size()) {
return false;
}
action.accept(currentBatch.get(batchIndex++));
return true;
}
private void loadNextPage() {
if (currentPage > lastPage) {
currentBatch = null;
return;
}
currentBatch = pageFetcher.apply(currentPage);
currentPage++;
batchIndex = 0;
if (currentBatch.isEmpty() && currentPage <= lastPage) {
loadNextPage();
}
}
@Override
public Spliterator<T> trySplit() {
int totalPages = lastPage - currentPage + 1;
if (totalPages <= 1) {
return null;
}
int mid = currentPage + totalPages / 2;
int oldLast = lastPage;
this.lastPage = mid - 1;
return new PagedSpliterator<>(pageSize, mid, oldLast, pageFetcher);
}
@Override
public long estimateSize() {
long pages = Math.max(0, lastPage - currentPage + 1L);
return pages * pageSize;
}
@Override
public int characteristics() {
return ORDERED | IMMUTABLE | SUBSIZED;
}
}
上面的实现里，currentPage和lastPage表示当前Spliterator负责的页区间。tryAdvance首先检查本地批次currentBatch是否还有未消费的元素，如果没有就通过loadNextPage向pageFetcher请求下一页。这样远程调用只会在本地批次耗尽时发生。trySplit按页编号对半切分：计算剩余页数，找到中点，把中点之后的页区间交给新实例，当前实例负责中点之前的页。由于每个新实例都有独立的currentPage、lastPage和currentBatch，并行线程之间不会互相干扰。
estimateSize按剩余页乘以pageSize估算。需要注意最后一批可能不足一页，这个估算会偏大。如果调用方要求精确数量，需要传入总元素数并在最后页做修正。characteristics返回ORDERED、IMMUTABLE和SUBSIZED，表示元素顺序一致、数据源不可变、拆分后每个子Spliterator的estimateSize仍然准确。这里返回SUBSIZED其实只在pageSize整除或总量已知并修正时成立，后面会专门讨论。
将该Spliterator接入Stream非常简单：
PagedSpliterator<String> spliterator = new PagedSpliterator<>(
100, 0, 49, page -> remoteService.fetchPage(page)
);
Stream<String> stream = StreamSupport.stream(spliterator, true);
stream.filter(s -> s.contains("error"))
.forEach(System.out::println);
StreamSupport.stream的第二个参数true表示创建并行流。当终端操作触发时，ForkJoinPool会调用trySplit拆分任务，每个子任务通过tryAdvance拉取自己区间内的页。如果数据源是只读的远程接口，这个模型能有效降低首次加载延迟和内存占用。
特征值设置与拆分粒度控制
characteristics返回的标志位不是随便组合的，它会直接影响Stream框架的优化路径。ORDERED表示元素在遍历时遵循固定的顺序，例如分页接口按页号从小到大返回。IMMUTABLE表示在流消费期间源数据不会发生结构性变化，可以安全地让多个线程读取同一批元素。SIZED表示estimateSize的返回值精确，而非估计值。SUBSIZED表示trySplit之后，每个子Spliterator的estimateSize也精确。
很多自定义实现会在这里踩坑：页大小固定，但总元素数不一定能整除页大小，最后一批元素不足一页。此时如果仍返回SIZED和SUBSIZED，而estimateSize简单用剩余页数乘以pageSize，就会高估最后一个子任务的大小。高估本身不一定导致错误，但可能让框架做出不合理的任务划分或容器预分配。更稳妥的做法是在总量未知或最后一批不满时，去掉SIZED和SUBSIZED，只保留ORDERED和IMMUTABLE。如果总量已知，可以像下面这样精确计算。
// 若总量已知且页大小固定，可精确计算最后页元素数
private long totalElements;
@Override
public long estimateSize() {
long elementsBefore = (long) currentPage * pageSize;
return Math.max(0, totalElements - elementsBefore);
}
@Override
public int characteristics() {
return ORDERED | IMMUTABLE | SIZED | SUBSIZED;
}
拆分粒度同样需要控制。如果远程调用延迟较高，拆得过细会导致大量极小任务同时发起页请求，反而拖垮上游服务。可以在trySplit中设置最小页数阈值，例如剩余页数少于3页时返回null，让任务保持一定大小。针对不同页大小和接口耗时，阈值可以调整。一般建议单任务至少包含几十到几百个元素。
@Override
public Spliterator<T> trySplit() {
int pages = lastPage - currentPage + 1;
if (pages <= 2) {
return null;
}
int mid = currentPage + pages / 2;
int oldLast = lastPage;
this.lastPage = mid - 1;
return new PagedSpliterator<>(pageSize, mid, oldLast, pageFetcher);
}
另一个常见问题是共享可变状态。假如自定义Spliterator内部缓存了一个共享列表，多个线程在tryAdvance中同时读取同一个列表游标，会引发竞态条件。拆分出的实例必须拥有独立的边界变量和独立的本地批次，或者使用不可变数据结构。对于分页远程数据源，每个实例独立维护currentBatch即可避免大多数并发问题。
CONCURRENT特征不要随意添加。它表示数据源即使在遍历过程中被其他线程修改，也能保证遍历一致性。大多数远程分页接口、文件读取器并不满足这一点，只有像ConcurrentHashMap这类容器的Spliterator才适合返回CONCURRENT。错误添加该特征可能掩盖真实的数据竞争，导致难以排查的偶发问题。
与Spliterators工具类的对比及落地建议
Java提供了一个Spliterators工具类，可以把普通Iterator包装成Spliterator。如果已经有现成的Iterator，可以调用Spliterators.spliteratorUnknownSize，它允许指定特征值，但trySplit通常只能返回null，不适合并行流。另一个重载方法允许传入大小，但拆分仍然基于Iterator顺序遍历，无法像自定义页区间那样高效地直接定位中段。对于能够按索引或页号定位的数据源，手动实现Spliterator的收益更明显。
什么时候适合自定义Spliterator？只要数据源满足两个条件之一，就值得考虑：第一，源本身支持跳过、分页、区间读取等随机访问能力；第二，加载全部元素到内存不可接受。典型场景包括数据库游标、搜索引擎分页接口、OSS对象遍历、日志文件按行读取等。对于本身就装在内存里的集合，直接用stream()即可，没必要重新造。
落地时建议遵循一个顺序：先用串行流验证tryAdvance和边界条件，再打开parallel()测试trySplit。可以写一个简单的CountDownLatch或打印线程名来确定任务确实被拆到多个线程。测试时重点关注最后一页不完整、总页数为奇数、trySplit返回null后剩余元素是否还能被完整消费。特征值调整可以放在最后，因为ORDERED、IMMUTABLE这些标志不影响正确性，主要影响性能。
总体来看，把自定义数据源接入集合框架的Stream能力，关键是实现一个边界清晰、拆分独立的Spliterator。相比直接依赖Iterator包装，自定义trySplit能更充分利用并行流，而estimateSize和characteristics则决定了流框架能否做出高效的任务划分。掌握这些方法后，远程分页、分块文件读取和内存映射数据都能以惰性、流式的方式融入现有Stream处理链。
Spliterator接口自定义Stream源Java集合框架修改时间：2026-09-20 21:29:21