Akka Streams 的 batch 操作符:面向慢下游的背压感知聚合指南
Akka Streams 的 batch 操作符:面向慢下游的背压感知聚合指南
batch 是 Akka Streams 中一类"背压感知"(Backpressure aware)操作符,用于在下游消费速度慢于上游生产速度时,把连续到达的元素通过 seed 与 aggregate 函数折叠为一个聚合值(summary),从而让上游不必被迫停下、下游也不必被淹没。阅读本文后,你将掌握 batch 的完整签名与语义、与 conflate/batchWeighted 等相似操作符的区别、其底层 GraphStage 实现原理,以及基于官方测试用例的可运行示例。本文以 batch.md 为核心骨架,并结合 akka-stream 源码与测试展开。
batch 是什么:允许更慢的下游
在 Akka Streams 的流式处理中,上游与下游的速度并不总是匹配的。当下游更慢时,如果上游继续全速生产,要么被迫背压(backpressure)停顿,要么需要把来不及消费的元素暂存起来。batch 提供的策略是:把来不及消费的元素聚合(aggregate)成一个汇总值,例如对整数求和、把 ByteString 拼接起来、或把元素收集进一个列表,从而用"信息密度更高"的批量结果代替逐条传递。
官方文档对它的定义是:
Allow for a slower downstream by passing incoming elements and a summary into an aggregate function as long as there is backpressure and a maximum number of batched elements is not yet reached.
即:只要有背压存在,并且尚未达到允许的最大批量元素数,就把新到的元素与当前的汇总值(summary)一起喂给聚合函数;一旦达到最大值而下游仍然在背压,batch 自身也会开始背压上游。
这一语义决定了它的适用场景:
- 上游是高频数据源(如传感器读数、日志事件、股票行情),下游是慢速消费者(如数据库写入、外部 HTTP 调用);
- 你可以接受"结果以聚合形态出现"(求和、计数、拼接),而不是关心每一个原始元素;
- 你希望对聚合结果的"批量上限"做硬性约束,防止无限聚合导致内存或语义失控。
操作符签名
batch 同时定义在 Source 与 Flow 上,Scala 与 Java API 的签名如下(对应文档中的 Source.batch / Flow.batch):
// Scala
def batchS(aggregate: (S, Out) => S): Repr[S]
// Java
def batchS
三个参数的含义:
| 参数 | 类型 | 说明 |
|---|---|---|
max |
Long |
允许批量聚合的最大元素个数,必须是正的非零值。达到该上限后若下游仍背压,batch 转而对上游背压 |
seed |
Out => S |
当开始聚合(收到第一个未被聚合的元素)时,把该元素转换为汇总类型 S 的初始值 |
aggregate |
(S, Out) => S |
接收当前已聚合的值与新到的元素,产出一个新的聚合值 |
返回类型是 Repr[S],即元素类型变为聚合类型 S 的同类流。注意聚合类型 S 可以完全不同于输入类型 Out,这正是它比 conflate 更灵活的地方。
Reactive Streams 语义
根据官方文档,batch 在 Reactive Streams 层面的行为契约是:
- emits(发射):当下游停止背压,并且存在一个已聚合(batched)的元素可用时;
- backpressures(背压):当已批量聚合的元素达到
max上限,并且下游仍在背压时; - completes(完成):当上游完成,并且"可能 pending(挂起)"的元素被排空(drained)之后。
其中最后一条提到的 "possibly pending element" 与 batch 的一个实现特性直接相关:它会主动(eagerly)向上游拉取元素,这可能导致上游完成时,恰好还有一个被拉取但尚未并入聚合值的元素停留在内部状态中;batch 必须先把这个 pending 元素用 seed 处理并排空,才能完成整个流。
内部实现原理:从源码看 batch 的运转
batch 在 akka-stream 中最终通过 via 连接到一个内部的 GraphStage 实现,见 Flow.scala#L2076-L2079:
def batchS(aggregate: (S, Out) => S): Repr[S] =
via(
Batch(max, ConstantFun.oneLong, seed, aggregate)
.withAttributes(DefaultAttributes.batch and SourceLocation.forLambda(aggregate)))
核心实现类为 akka.stream.impl.fusing.Batch(标注为 @InternalApi),定义于 Ops.scala#L1042-L1172。从源码结构看,它维护了三个关键内部状态:
agg: Out:当前累积的聚合值;left: Long:还剩余可聚合的元素额度,初始化为max;pending: In:因达到max上限而暂时无法并入聚合值的"挂起"元素。
其核心处理逻辑 onPush 可以归纳为三步(Ops.scala#L1090-L1127):
- 若当前还没有聚合值(
agg == null),用seed(elem)创建初始聚合值,并扣减额度; - 否则,若剩余额度不足以容纳该元素(
left < cost),把元素暂存为pending(此时达到上限,不再向上游继续拉取,从而对上游背压); - 否则调用
aggregate(agg, elem)把元素并入聚合值,继续扣减额度。
而 onPull(下游请求元素)与 flush 则负责把聚合值推给下游并重置额度(Ops.scala#L1064-L1086)。值得注意的是,Batch 结构体还带有一个 costFn: In => Long 字段,而 batch 传入的是 ConstantFun.oneLong——即每个元素成本恒为 1,因此 max 在这里就等价于"元素个数上限";这一成本函数机制被 batchWeighted 复用,以支持按权重而非个数来限制批量。
另外两个实现细节值得说明:
- 监督策略(SupervisionStrategy):源码注释与 Flow.scala#L2060 明确说明
batch遵循ActorAttributes.SupervisionStrategy。在 Ops.scala#L1057 中,seed/aggregate抛出的非致命异常会交给 decider 处理:Stop使流失败、Restart重置内部状态(agg/left/pending全部清空,见restartState)、Resume则跳过出错元素继续。 - 上下文传播(Context Propagation):
onPush与onPull中分别调用contextPropagation.suspendContext()/resumeContext(),保证聚合计算期间不会被异步中断污染上下文。
实战示例:结合官方测试用例
akka-stream 的官方测试 FlowBatchSpec.scala 完整覆盖了 batch 的各种典型场景,下面逐一解读,你可以直接复制为可运行示例。
场景一:速率相同时原样透传
当上下游速率一致、没有任何背压时,batch 不会做任何聚合,元素逐个原样通过(FlowBatchSpec.scala#L22-L40):
Source
.fromPublisher(publisher)
.batch(max = 2, seed = i => i)(aggregate = _ + _)
.to(Sink.fromSubscriber(subscriber))
.run()
for (i <- 1 to 100) {
sub.request(1)
publisher.sendNext(i)
subscriber.expectNext(i) // 每个元素原样收到
}
即使设了 max = 2,只要下游每次及时 request,元素就逐一透传,说明 batch 只在存在背压时才触发聚合。
场景二:下游沉默时聚合
当下游不请求、上游持续发元素时,batch 把所有元素聚合成一个列表(FlowBatchSpec.scala#L42-L60):
Source
.fromPublisher(publisher)
.batch(max = Long.MaxValue, seed = i => List(i))(aggregate = (ints, i) => i :: ints)
.to(Sink.fromSubscriber(subscriber))
.run()
for (i <- 1 to 10) publisher.sendNext(i) // 下游不 request
subscriber.expectNoMessage(1.second) // 没有元素发射
sub.request(1)
subscriber.expectNext(List(10, 9, 8, 7, 6, 5, 4, 3, 2, 1)) // 一次性得到聚合结果
这里展示了 seed = i => List(i) 与 aggregate = (ints, i) => i :: ints 的组合:把元素收集成列表,max = Long.MaxValue 意味着几乎不设上限,只受内存约束。
场景三:达到 max 后对上游背压
这是 batch 背压行为的关键测试(FlowBatchSpec.scala#L72-L103):
Source
.fromPublisher(publisher)
.batch(max = 2, seed = i => i)(aggregate = _ + _)
.to(Sink.fromSubscriber(subscriber))
.run()
sub.request(1); publisher.sendNext(1); subscriber.expectNext(1)
sub.request(1); publisher.sendNext(2); subscriber.expectNext(2)
publisher.sendNext(3)
publisher.sendNext(4)
subscriber.expectNoMessage(500.millis) // 3、4 被聚合(3+4=7)但不下发
sub.request(1)
subscriber.expectNext(7) // 聚合结果 7
max = 2 意味着批量上限是 2 个元素。当 3 到达时进入 seed 成为聚合值,4 到达时与 3 聚合为 7,此时已达上限;若此时再发元素,就会触发 batch 对上游的背压。测试注释也点明了竞态细节:"The request can be in race with the above onNext(4) so the result would be either 3 or 7"——即在边界上结果可能是 3 或 7,体现了流的时序性。
场景四:长链与 buffer 组合
- 在变速链上对 1000 个元素分批求和,最终结果等于
(1 to 1000).sum = 500500(FlowBatchSpec.scala#L62-L70),验证了聚合的正确性; - 与
buffer组合使用时(FlowBatchSpec.scala#L105-L111),batch(max = Long.MaxValue, seed = i => i)(aggregate = _ + _)先把 1 到 50 全部聚合为总和 1275,再交给下游的buffer(50, OverflowStrategy.backpressure)与runFold,结果依然等于(1 to 50).sum。
batch 与相似操作符的对比
在 Akka Streams 中,处理"上游快、下游慢"的操作符一族还包括(相关文档位于同一目录):
| 操作符 | seed | 成本/权重 | 主要差异 |
|---|---|---|---|
batch |
有 | 每个元素成本恒为 1(ConstantFun.oneLong) |
按元素个数限制批量,达到 max 后对上游背压 |
| batchWeighted | 有 | 由 costFn 计算 |
按权重限制批量,同一 Batch 实现只是换了成本函数 |
| conflate | 无(seed = identity) |
无限制 | 永不背压、无限聚合,仅当上游快于下游时聚合 |
| conflateWithSeed | 有 | 无限制 | 与 batch 同族但不设 max,聚合没有上限 |
从源码看,conflate 本质上就是 conflateWithSeed(identity)(见 Flow.scala#L2049-L2050),而 batchWeighted 与 batch 共享同一个 Batch GraphStage,仅成本函数不同(分别见 Flow.scala#L2076-L2079 与 Flow.scala#L2039)。它们共同遵守"只在存在背压时聚合、下游更快时绝不重复或丢元素"的契约。
典型使用模式与注意事项
综合文档语义与实现,使用 batch 时有几点值得注意:
max必须为正非零:这是源码注释明确给出的约束(Flow.scala#L2072),传入 0 或负数属于错误用法。- 聚合要可折叠、可重复:
aggregate会被反复调用,且最终结果只有聚合值(原始元素可能已被合并),因此应选择满足结合律的折叠操作,并确保seed对任意首个元素都能生成合法初始值。 - 背压是硬上限:与
conflate的"无限聚合"不同,batch达到max后会对上游背压,这是防止内存无界增长的保护机制;max = Long.MaxValue则可以近似"无限聚合",代价是内存与聚合值的持续膨胀。 - eager pull 带来的 pending 元素:文档明确警告"Will eagerly pull elements, this behavior may result in a single pending (i.e. buffered) element which cannot be aggregated to the batched value"——即最多可能有一个挂起元素无法并入聚合值,它会在上游完成后被单独处理并排空,这正是"completes"语义中 "a possibly pending element was drained" 的由来。
- 适合的典型场景:计数/求和类遥测指标聚合、把高频小消息合并为批量写入(如数据库批量插入)、
ByteString拼接等;若需要按字节数而非条数限流,请改用batchWeighted。
小结
batch 是 Akka Streams 背压策略工具箱中"以聚合换吞吐"的代表操作符:它用 seed + aggregate 把背压窗口内的元素折叠为汇总值,用 max 给出批量上限,并严格遵循 emits / backpressures / completes 三态契约。通过 batch.md 文档、Flow.scala 的 API 定义、Ops.scala 的 GraphStage 实现,以及 FlowBatchSpec.scala 的测试用例,你可以放心地在自己的流式管线中选用它,并通过 batchWeighted 平滑迁移到按权重控制的批量策略。