Java Stream Gatherer 终止输入并输出尾部状态

Gatherer 的“终止输入”不是让 integrator 返回 false，而是上游已经没有下一个元素时进入 finisher。如果目标是把计数、最后一条记录或聚合摘要作为一条结果输出，应把它们放进中间状态，在 finisher 中调用 downstream.push。这样非空流通常产生一条尾部结果，空流则可以明确地产生零条结果。

正常结束交给 finisher，提前停止才使用 integrator 的 false；需要维护顺序状态时，优先从 ofSequential 开始。

先分清 finisher 和短路返回值

一个 Gatherer 可以理解为四个协作点：初始化状态、整合元素、合并分区状态、结束时把状态转成下游结果。顺序 Gatherer 没有可用的合并逻辑时，输入会按遇到顺序交给 integrator；上游耗尽后，再调用一次 finisher。

integrator 返回 false 表示“不再希望继续接收元素”，它是短路信号，不是普通的 EOF 标记。比如找到第一个满足条件的元素后可以停止；若只是想在最后补发一条摘要，应该让整合函数继续返回 true，把补发动作放到 finisher。

用一个状态对象保存尾部信息

示例把输入字符串拼成摘要，同时保存输入数量和最后一个元素。状态只属于当前 Gatherer 评估过程，不能被外部缓存，也不要在回调结束后继续持有它。

import java.util.List;
import java.util.stream.Gatherer;
import java.util.stream.Stream;

final class TailState {
    final StringBuilder summary = new StringBuilder();
    int count;
    String last;
}

static Gatherer tailState() {
    return Gatherer.ofSequential(
        TailState::new,
        Gatherer.Integrator.ofGreedy((state, element, downstream) -> {
            // 这里只更新状态；正常结束不在这里推送尾部结果。
            state.count++;
            state.last = element;
            if (state.summary.length() > 0) state.summary.append(" | ");
            state.summary.append(element);
            return true; // true 表示继续接收上游元素
        }),
        (state, downstream) -> {
            // 输入耗尽后只输出一次最终状态；空流没有可输出的状态。
            if (state.count > 0) {
                downstream.push("count=" + state.count
                    + ", last=" + state.last
                    + ", summary=" + state.summary);
            }
        });
}

List result = Stream.of("A", "B", "C")
    .gather(tailState())
    .toList();
// result 只有一项：count=3, last=C, summary=A | B | C

这里的 downstream 是下一阶段的出口，finisher 可以推送零条或多条结果。示例选择“非空流一条、空流零条”的语义，调用方就能用列表是否为空判断是否真的收到输入。

尾部状态的输出边界在哪里

下面这张结构图强调的是数据关系，不是编辑器或终端截图：每个输入只修改状态，只有输入耗尽后才由 finisher 把状态快照送入下游。

什么时候改用 Gatherers.fold

如果只是顺序地把每个输入折叠成一个结果，可以直接使用 Gatherers.fold。它表达的是“没有可用 combiner，或归约天然依赖顺序”的场景，并且在没有异常时只产生一个元素。自定义 Gatherer 的价值在于尾部对象不只是一个单值：你可以同时保存计数、最后元素、校验摘要，或者在结束时按业务格式输出多条记录。

需要注意，ofSequential 明确放弃了并行合并能力。若要支持并行，必须让局部状态有可靠的结合规则，并使用 Gatherer.of 提供 combiner；不能简单地把一个有顺序依赖的 StringBuilder 状态搬进并行流。

常见问题与边界

为什么 finisher 没有被调用到？

先确认流确实执行了终端操作，并且不是在更早阶段抛出了异常。惰性 Stream 只有被消费时才会运行 Gatherer。

可以在 integrator 中直接输出最后一条吗？

如果“最后一条”只有在输入结束后才能确定，就不应该在 integrator 中输出；否则还会继续收到后续元素，容易产生重复或错误的尾项。

空流需要输出一个默认对象怎么办？

把默认对象的语义显式写进 finisher，并用独立的“是否收到输入”标志区分空流和真实的默认值，避免把缺失数据伪装成业务记录。

收尾判断

设计这类 Gatherer 时只看三点：状态是否只在当前评估中使用，正常结束是否统一走 finisher，以及空流和并行边界是否写清楚。这样“输入结束后输出尾部状态”就不会和短路、终端操作或线程安全混成一个问题。