RxGo Scan 操作符实战:对顺序流做累积聚合并逐值发射
RxGo Scan 操作符实战:对顺序流做累积聚合并逐值发射
RxGo 的 Scan 操作符将二元函数按序应用于 Observable 发射的每一个元素,并把每一步的累积结果依次发射出去,是 Go 反应式流中实现"滚动求和、状态折叠、累积统计"的标准手段。本文以 Scan 文档 为主线,结合 observable_operator.go 中的真实实现与 observable_operator_test.go 的测试用例,讲解 Scan 的 API 签名、累积器(accumulator)生命周期、错误传播机制,以及它"强制顺序执行"的底层原因和可选配置项。
Scan 的核心语义:每步都发射,而不是只留结果
Scan 操作符文档 对其定义非常简洁:
Apply a function to each item emitted by an Observable, sequentially, and emit each successive value.
即:顺序地将函数应用到上游发射的每个元素,并发射每一次计算得到的中间值。这与 Map(对每个元素做无状态映射)和 Reduce(只发射最终折叠结果)形成明显区别:
Map的输出数量等于输入数量,每个输出只依赖当前元素;Scan的输出数量也等于输入数量,但每个输出依赖"当前累积值 + 当前元素";Reduce则只在流结束时发射一个最终值(从源码结构看,reduceOperator 的end方法 在序列结束时才把累积值写出)。
API 定义与 Func2 签名
Scan 在 Observable 接口 中的声明为:
Scan(apply Func2, opts ...Option) Observable
其中 Func2 在 types.go 中定义:
// Func2 defines a function that computes a value from two input values.
Func2 func(context.Context, interface{}, interface{}) (interface{}, error)
两个 interface{} 参数分别代表当前累积值(accumulator)与当前元素(element),返回值是新的累积值。值得注意的是,函数以 interface{} 收参、以 interface{} 返回,类型转换(如 acc.(int))必须由回调函数自行完成,库层不做类型推断。
文档示例:累积求和
doc/scan.md 给出的标准示例是一个滚动求和:
observable := rxgo.Just(1, 2, 3, 4, 5)().
Scan(func(_ context.Context, acc interface{}, elem interface{}) (interface{}, error) {
if acc == nil {
return elem, nil
}
return acc.(int) + elem.(int), nil
})
输出为:
1
3
6
10
15
逐步推演:第一个元素 1 到来时累积值还是初始的 nil,直接返回 1;随后 1+2=3、3+3=6、6+4=10、10+5=15。也就是说 Scan 发射的是部分和序列,而不是一个总和——这正是它与 Reduce/求和类操作的关键差异,适合做滚动均值、增量计数、逐点状态跟踪等场景。
源码解析:累积值如何被保存与推进
Scan 的实现非常短小,但信息量完整:
// Scan apply a Func2 to each item emitted by an Observable, sequentially, and emit each successive value.
// Cannot be run in parallel.
func (o *ObservableImpl) Scan(apply Func2, opts ...Option) Observable {
return observable(o.parent, o, func() operator {
return &scanOperator{
apply: apply,
}
}, true, false, opts...)
}
type scanOperator struct {
apply Func2
current interface{}
}
func (op *scanOperator) next(ctx context.Context, item Item, dst chan<- Item, operatorOptions operatorOptions) {
v, err := op.apply(ctx, op.current, item.V)
if err != nil {
Error(err).SendContext(ctx, dst)
operatorOptions.stop()
return
}
Of(v).SendContext(ctx, dst)
op.current = v
}
从源码结构看,有四个关键事实:
- 初始累积值为
nil。scanOperator.current是interface{}零值,因此回调函数第一次被调用时acc必为nil,文档示例中if acc == nil的判断就是在处理这个"首个元素"的特殊情况。如果你希望有非零初始值,可以在链式调用前用StartWith类操作注入,或在回调中把nil解释为你想要的首值。 - 错误会立即终止管道。回调返回
error时,实现通过Error(err).SendContext(ctx, dst)把错误包装成 Item 下发并调用operatorOptions.stop(),后续元素不再处理。上游错误则由err方法 走defaultErrorFuncOperator,同样转发错误并停止。 end是空实现。scanOperator 的end方法 什么也不做——因为每一步的累积值都已经随next发射出去了,流结束时没有"补发最终值"的语义。- 每次成功计算后立即更新
op.current = v,保证下一步拿到的是最新累积值,这是严格顺序语义的基础。
为什么 Scan 无法并行
Scan 调用内部 observable 工厂时传入了 forceSeq=true(见 observable 工厂函数):无论是否传入 WithPool/WithCPUPool,只要 forceSeq 为真,都会走 runSequential 路径。原因在于 Scan 的正确性依赖"上一步的输出即下一步的输入",并行化会破坏累积顺序,因此源码注释明确写着 Cannot be run in parallel。
这也解释了两个现象:
- doc/scan.md 的 Options 列表中不包含
WithPool/WithCPUPool(对比 doc/map.md 的选项列表则包含它们); - 但 测试用例 Test_Observable_Scan_Parallel 依然传入了
WithCPUPool()——由于forceSeq生效,实际执行仍是顺序的,断言使用的HasItemsNoOrder(1, 3, 6, 10, 15)只是宽松地校验了集合一致性。可以推断该用例更多是回归验证"传并行选项不会导致崩溃或乱序"。
官方顺序测试 Test_Observable_Scan 则用 Assert(ctx, t, obs, HasItems(1, 3, 6, 10, 15)) 精确校验了顺序与内容,并与 doc/scan.md 的输出一致:
obs := testObservable(ctx, 1, 2, 3, 4, 5).Scan(func(_ context.Context, x, y interface{}) (interface{}, error) {
if x == nil {
return y, nil
}
return x.(int) + y.(int), nil
})
Assert(ctx, t, obs, HasItems(1, 3, 6, 10, 15))
两个测试都使用 goleak.VerifyNone(t) 确认执行结束后没有泄漏的 goroutine——这提示在实际项目中,消费 Scan 结果时应当完整消费流或让上游正常结束(例如用 Run() 阻塞消费,参见 doc/run.md)。
可用的配置选项
按照 doc/scan.md 的说明,Scan 支持以下函数式选项(语义见 doc/options.md,选项实现位于 options.go):
| 选项 | 说明 | 示例 |
|---|---|---|
WithBufferedChannel(capacity int) |
配置输出 channel 的容量 | rxgo.WithBufferedChannel(1) |
WithContext(ctx) |
传入 context,Observable 会监听其 done 信号以关闭自身 | rxgo.WithContext(ctx) |
WithObservationStrategy(strategy) |
Lazy(默认):Observer 订阅时才开始消费;Eager:Observable 创建时即开始消费 |
rxgo.WithObservationStrategy(rxgo.Lazy) |
WithErrorStrategy(strategy) |
StopOnError(默认)出错即停止;ContinueOnError 出错后继续处理,且该策略会向父 Observable 传播 |
rxgo.WithErrorStrategy(rxgo.StopOnError) |
WithPublishStrategy() |
创建 Connectable Observable(见 README.md 的 Connectable Observable 一节),该选项会向父 Observable 传播 | rxgo.WithPublishStrategy() |
组合写法与 doc/options.md 中的示例一致:
observable := rxgo.Just(1, 2, 3, 4, 5)().
Scan(func(_ context.Context, acc interface{}, elem interface{}) (interface{}, error) {
if acc == nil {
return elem, nil
}
return acc.(int) + elem.(int), nil
},
rxgo.WithContext(ctx),
rxgo.WithBufferedChannel(1))
使用建议与小结
结合文档与源码,实际使用 Scan 时值得注意三点:
- 类型安全靠回调自己保证。
Func2全部使用interface{},回调中的acc.(int)、elem.(int)这类断言失败会 panic,建议在函数入口用类型断言的逗号 ok 形式返回error,让 错误传播机制 干净地终止管道。 - 务必处理
acc == nil的初始态,或显式决定nil的语义;否则第一个元素就会触发空指针式断言失败。 - 不要期待并行加速。
Scan因累积依赖被硬编码为顺序执行(forceSeq=true),若需要并行处理,应选择Map等无状态操作符并配合WithPool/WithCPUPool;Scan更适合作为管道末段的状态汇总步骤,再配合Take、First等操作截取特定位置的累积值。
Scan 是 RxGo 转换类操作符中语义最纯粹的"有状态 Map":README.md 将其归入 Transforming Observables,其"每步发射、顺序执行、错误即停"的行为都由 observable_operator.go 中约三十行代码直接决定,阅读该实现是掌握其行为边界的最可靠途径。