Akka Streams batchWeighted 操作符详解:按权重批量聚合以平滑背压
Akka Streams batchWeighted 操作符详解:按权重批量聚合以平滑背压
导读
batchWeighted 是 Akka Streams 中面向背压(backpressure)场景的关键操作符:当下游消费速度慢于上游生产速度时,它通过 costFn 计算每个元素的权重,并在"累计权重未超过 max 上限"的前提下,用 seed 与 aggregate 函数把多个传入元素聚合为一个批量结果,从而让慢速下游不必逐条处理、快速上游也不至于被阻塞。本文以官方文档 batchWeighted 为骨架,结合源码实现与测试用例,带你掌握该操作符的签名、语义、超重元素处理、监督策略等完整实战细节。
一、操作符定位与适用场景
batchWeighted 属于 Akka Streams 的 @ref背压感知操作符(Backpressure aware operators) 家族。它与 batch、conflate、conflateWithSeed 属于同一类"上游快、下游慢"的缓冲/聚合工具,区别在于:
conflate只聚合,无数量或权重上限;batch以"元素个数"为上限(每个元素权重恒为 1,源码中对应ConstantFun.oneLong);batchWeighted以"累计权重"为上限,每个元素的权重由costFn单独计算,更贴近真实场景。
典型场景:将大量 ByteString 片段按字节数批量拼接后交给慢速消费者,或把高频小消息按"条数/大小预算"聚合后再落库,既能降低下游压力,又能控制单批数据的规模。
二、函数签名
batchWeighted 定义在 FlowOps trait 中,Scala 与 Java DSL 均可直接使用,也可用于 Source / Flow / SubFlow / SubSource(见 javadsl/Source.scala、javadsl/SubFlow.scala 等)。
Scala 签名(来自 scaladsl/Flow.scala#L2109-L2112):
def batchWeightedS(aggregate: (S, Out) => S): Repr[S]
Java 签名(来自 javadsl/Flow.scala#L2039-L2044):
Flow<In, S, Mat> batchWeighted(
long max,
akka.japi.function.Function<Out, Long> costFn,
akka.japi.function.Function<Out, S> seed,
akka.japi.function.Function2<S, Out, S> aggregate)
参数含义:
| 参数 | 类型 | 说明 |
|---|---|---|
max |
Long |
允许批量聚合的最大总权重,必须为正且非零;达到上限后若下游仍在背压,本操作符将向上游背压 |
costFn |
Out => Long |
计算单个元素权重的函数,决定每个元素占用多少"预算" |
seed |
Out => S |
用第一个尚未被消费的元素作为起点,生成批量的初始状态 |
aggregate |
(S, Out) => S |
接收当前批量状态与当前待聚合元素,产出新的批量状态 |
三、核心语义与行为描述
官方文档对 batchWeighted 的定义是:当下游更慢且存在背压时,只要"已批量元素的累计权重"未达到 max 上限,就持续把传入元素与当前汇总值交给 aggregate 函数聚合;一旦累计权重达到上限且下游仍在背压,则本操作符转而对上游背压。
3.1 Reactive Streams 语义
文档明确给出了三条契约:
- emits(发射):当下游停止背压,且存在可用的已批量元素时发射;
- backpressures(背压):已批量元素达到
max权重上限,且下游仍在背压时,向上游背压; - completes(完成):上游完成,且"可能挂起(pending)"的元素已被排空时完成。
3.2 上游的"急切拉取"行为
文档特别强调:batchWeighted 会急切地从上游拉取元素(eagerly pull),这一行为可能导致存在一个"挂起(pending)"元素——即当前批量已达到权重上限而无法再聚合进下一个元素时,该元素被暂存。源码中对应 Ops.scala#L1108-L1109:当 left < cost 时(剩余预算不足以容纳新元素),元素被赋值给 pending 字段而不是参与聚合。
3.3 超重元素(单个元素权重大于总限额)
当单个元素的成本大于整个 max 限额时,batchWeighted 依然会为它聚合。源码注释(scaladsl/Flow.scala#L2089-L2092)给出的处理流程是:
- 先发射此前已批量好的元素;
- 随后将"超重"元素单独经
seed处理后直接发射,不与其他元素聚合; - 之后继续批量聚合后续到达的元素。
这一设计保证了任何元素都不会丢失或无限期滞留。
四、源码级原理:Batch GraphStage 内部机制
batchWeighted 与 batch 共用同一个底层实现——位于 impl/fusing/Ops.scala#L1042-L1172 的 Batch[In, Out] GraphStage(batch 传入 ConstantFun.oneLong 作为 costFn,即每个元素权重恒为 1)。从源码结构可以梳理出以下关键机制:
4.1 内部状态
private var agg: Out = null.asInstanceOf[Out] // 当前已聚合的批量值
private var left: Long = max // 剩余可用权重预算
private var pending: In = null.asInstanceOf[In] // 挂起元素(预算不足时暂存)
4.2 onPush 分支逻辑(Ops.scala#L1090-L1127)
每个上游元素到达时,costFn 先计算其权重,然后按三种情况处理:
agg == null(尚无批量值):调用seed(elem)初始化批量状态,并扣减预算;left < cost(预算不足):元素放入pending,不再聚合;- 否则:调用
aggregate(agg, elem)合并元素并扣减预算。
随后若下游可接收(isAvailable(out))则执行 flush() 发射当前批量并重置预算;若 pending == null 则继续拉取上游。
4.3 onPull / flush 的发射路径
flush()(Ops.scala#L1064-L1086)先把聚合好的 agg 推给下游并重置 left = max,再把 pending 元素经 seed 变成新的批量起点;上游完成(onUpstreamFinish)后,只有 agg 为 null 时才会立即完成,否则必须等待下游把挂起的批量全部取走。
五、监督策略(Supervision)
源码注释明确 batchWeighted 遵循 ActorAttributes.SupervisionStrategy 属性(scaladsl/Flow.scala#L2060)。seed 与 aggregate 函数若抛出非致命异常(NonFatal),会交给监督决策器处理(Ops.scala#L1074-L1082):
Stop:直接failStage(ex)失败整个流;Restart:调用restartState()重置agg、left、pending后重新开始;Resume:丢弃出错的元素(跳过该元素,不聚合、不暂停)。
六、实战示例与测试验证
6.1 官方测试用例
仓库中的专项测试 FlowBatchWeightedSpec.scala 给出了一个"不聚合超重元素"的可运行示例:
Source
.fromPublisher(publisher)
.batchWeighted(max = 3, _ => 4, seed = i => i)(aggregate = _ + _)
.to(Sink.fromSubscriber(subscriber))
.run()
测试流程:max = 3,但每个元素 costFn 恒为 4(单个元素即超重)。发送 1、2 后请求 1 个元素,下游先收到经 seed 单独发射的 1;等待期间无新元素发射(expectNoMessage);再次请求后依次收到 2、3——验证了超重元素"各自单独发射、不互相聚合"的语义。
6.2 组合使用建议
batchWeighted 可与 conflate、limit、limitWeighted 等操作符对比选用(源码注释 scaladsl/Flow.scala#L2017 给出了相关操作符的交叉引用)。例如:
source
.batchWeighted(max = 100, costFn = b => b.length.toLong, seed = b => b) {
(acc, b) => acc ++ b
}
即按字节数聚合 ByteString,每批总字节数不超过 100,超重片段单独透传——这正是文档描述的"批处理与背压平滑"能力的直接落地。
七、小结
batchWeighted 通过"权重预算 + 聚合函数"的方式,为上游快、下游慢的流提供了一种可精确控制批量规模的背压缓冲方案。掌握其 max / costFn / seed / aggregate 四要素、超重元素单独透传、急切拉取产生 pending 元素、以及监督策略对异常的处理,即可在真实业务中安全、高效地使用该操作符。更多操作符语义可继续查阅 operators 索引 与 FlowOps.batchWeighted 源码注释。