RxGo Scan 操作符实战:对顺序流做累积聚合并逐值发射

原创2026-10-14 14:46:341,764 阅读
文章标签:后端

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
}

从源码结构看,有四个关键事实:

  1. 初始累积值为 nil。scanOperator.current 是 interface{} 零值,因此回调函数第一次被调用时 acc 必为 nil,文档示例中 if acc == nil 的判断就是在处理这个"首个元素"的特殊情况。如果你希望有非零初始值,可以在链式调用前用 StartWith 类操作注入,或在回调中把 nil 解释为你想要的首值。
  2. 错误会立即终止管道。回调返回 error 时,实现通过 Error(err).SendContext(ctx, dst) 把错误包装成 Item 下发并调用 operatorOptions.stop(),后续元素不再处理。上游错误则由 err 方法 走 defaultErrorFuncOperator,同样转发错误并停止。
  3. end 是空实现。scanOperator 的 end 方法 什么也不做——因为每一步的累积值都已经随 next 发射出去了,流结束时没有"补发最终值"的语义。
  4. 每次成功计算后立即更新 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 时值得注意三点:

  1. 类型安全靠回调自己保证。Func2 全部使用 interface{},回调中的 acc.(int)、elem.(int) 这类断言失败会 panic,建议在函数入口用类型断言的逗号 ok 形式返回 error,让 错误传播机制 干净地终止管道。
  2. 务必处理 acc == nil 的初始态,或显式决定 nil 的语义;否则第一个元素就会触发空指针式断言失败。
  3. 不要期待并行加速。Scan 因累积依赖被硬编码为顺序执行(forceSeq=true),若需要并行处理,应选择 Map 等无状态操作符并配合 WithPool/WithCPUPool;Scan 更适合作为管道末段的状态汇总步骤,再配合 Take、First 等操作截取特定位置的累积值。

Scan 是 RxGo 转换类操作符中语义最纯粹的"有状态 Map":README.md 将其归入 Transforming Observables,其"每步发射、顺序执行、错误即停"的行为都由 observable_operator.go 中约三十行代码直接决定,阅读该实现是掌握其行为边界的最可靠途径。

登录后查看全文
RxGo