Apache Beam Splittable DoFn 实战指南:突破单 Worker 并行瓶颈的 Java、Python、Go 三 SDK 完整实现与原理剖析
Apache Beam Splittable DoFn 实战指南:突破单 Worker 并行瓶颈的 Java、Python、Go 三 SDK 完整实现与原理剖析
导读:本文围绕 Apache Beam 中面向大输入集合并行处理的高级 transform——Splittable DoFn(SDF)展开。你将理解它如何把一个大输入划分为若干独立、可并行处理的 restriction 分块,掌握 Go、Java、Python 三个 SDK 下各自必须实现的注解/方法约定与完整示例代码,并读懂 RestrictionTracker / RTracker 底层
tryClaim、trySplit的动态切分与自检查点(self-checkpointing)原理,最终能够动手完成"用 Splittable DoFn 读取数据库"这样的实战练习。
一、为什么需要 Splittable DoFn:常规 DoFn 的并行瓶颈
在 Apache Beam 中,DoFn 是构成 ParDo transform 的最基本单元,对输入 PCollection 中的每一个元素执行用户自定义逻辑。但对于超大输入集合,常规 DoFn 有一个天然的瓶颈:每个输入元素对应的处理逻辑由单个 worker 执行,无法把一个元素内部的"大批量工作"进一步拆分给多个 worker 并行处理,从而导致处理速度缓慢、产生性能瓶颈。
Splittable DoFn 正是为打破这一瓶颈而设计。它允许一个 transform 将大的输入集合划分为更小的、相互独立的块(chunks),这些块可以被多个 worker 并行处理,从而获得更快、更高效的吞吐。
需要说明的是,Splittable DoFn 并非适用于任意场景,它天然面向能够被高效切分的数据源,例如:
- 文件:可以按字节偏移(offset)切分成多个片段,每个 worker 读取其中一段;
- 数据库:可以按主键范围、行偏移等划分查询区间,多个 worker 并发扫描不同分区。
在使用 Splittable DoFn 时,输入源会先被划分成一组 splits(分片),每个 split 可被一个 worker 独立处理。split 的数量并非预先写死,而是根据输入集合的规模与当前可用资源动态决定——这正是它能够应对数据规模波动、实现自动伸缩的关键。
在 tour-of-beam 的课程体系中,该主题位于 learning/tour-of-beam/learning-content/splittable-dofn,unit-info.yaml 将 splittable 单元标记为 ADVANCED(高级) 复杂度,并同时面向 Java、Python、Go 三个 SDK。
二、SDF 的核心概念:Restriction、Split 与 Tracker
在深入各 SDK 代码前,先建立三个核心概念:
| 概念 | 含义 |
|---|---|
| Restriction(限制) | 描述某个输入元素可被并行处理的工作范围。典型例子是字节/行偏移区间 [Start, End),即 OffsetRange。 |
| Split(分片) | 把一个 restriction 递归划分为若干子 restriction 的过程与产物,子 restriction 可被不同 worker 独立处理。 |
| RestrictionTracker / RTracker(跟踪器) | 在 ProcessElement 执行期间跟踪当前 restriction 的处理进度:记录已 claim(认领)的工作位置、支持 tryClaim 认领下一个工作块、支持 trySplit 把剩余工作切分出去交给别的 worker(动态分片)。 |
SDF 的处理流程可以概括为:初始 restriction 生成 → 递归切分 → 为每个子 restriction 创建 tracker → 在 ProcessElement 中循环 tryClaim 并处理已认领的块 → 处理完成后 checkDone 校验。
下面分别看三个 SDK 如何落地这套流程。
三、Go SDK:以 struct 方法实现 Splittable DoFn
Go SDK 中,Splittable DoFn 是一个 struct 及其一组方法,无需注解。需要实现的基本方法包括:
CreateInitialRestriction:为输入元素创建初始 restriction。函数接收DoFn实例、输入元素与Restriction实例,返回该元素的初始 restriction;SplitRestriction:把一个 restriction 拆分为更小的子 restriction,以便并行处理;RestrictionSize:返回一个 restriction 的大小(用于动态切分的决策依据);CreateTracker:为每个 restriction 创建sdf.LockRTracker,内部包装offsetrange.NewTracker;ProcessElement:用户自定义处理函数,对每个已认领的工作块执行实际读取/处理并发射输出。
课程示例位于 go-example/main.go,其核心 readFn 结构如下:
type readFn struct {
}
func (fn *readFn) CreateInitialRestriction(_ string, size int64) offsetrange.Restriction {
return offsetrange.Restriction{
Start: 0,
End: size,
}
}
func (fn *readFn) SplitRestriction(_ string, _ int64, rest offsetrange.Restriction) []offsetrange.Restriction {
splits := rest.SizedSplits(blockSize)
numSplits := len(splits)
if numSplits > 1 {
last := splits[numSplits-1]
if last.End-last.Start <= tooSmall {
// 最后一个分片过小,与上一个合并,避免产生碎片分片。
splits[numSplits-2].End = last.End
splits = splits[:numSplits-1]
}
}
return splits
}
func (fn *readFn) RestrictionSize(_ string, _ int64, rest offsetrange.Restriction) float64 {
return rest.Size()
}
// CreateTracker 为每个 restriction 创建 sdf.LockRTracker,包装 offsetRange.Tracker。
func (fn *readFn) CreateTracker(rest offsetrange.Restriction) *sdf.LockRTracker {
return sdf.NewLockRTracker(offsetrange.NewTracker(rest))
}
func (fn *readFn) ProcessElement(ctx context.Context, rt *sdf.LockRTracker, filename string, _ int64, emit func(string)) error {
log.Infof(ctx, "Reading from %v", filename)
// 打开文件、定位到 restriction 起始偏移,然后循环 tryClaim 逐行读取……
// 核心循环:
for rt.TryClaim(i) {
line, err := rd.ReadString('\n')
if err == io.EOF {
if len(line) != 0 {
emit(strings.TrimSuffix(line, "\n"))
}
// 结束前完成对 restriction 末尾的认领,避免校验报错。
rt.TryClaim(rt.GetRestriction().(offsetrange.Restriction).End)
break
}
if err != nil {
return err
}
emit(strings.TrimSuffix(line, "\n"))
i += int64(len(line))
}
return nil
}
这个示例展示了 SDF 的真实文件读取场景:Read 函数先用 expandFn 把 glob 展开成文件名列表,再用 sizeFn 获取每个文件的字节大小,最后 beam.ParDo(s, &readFn{}, sized) 触发 SDF 处理(见 main.go)。其中 blockSize = 64 * 1024 * 1024(64 MB)、tooSmall = blockSize / 4 定义了分片粒度:每个子 restriction 约 64 MB,若末尾碎片不足 16 MB 则合并进前一片,避免过小分片带来的调度开销。
底层契约:Go 的 sdf 包在 sdf.go 中定义了 RTracker 接口,其核心方法语义如下:
TryClaim(pos):在ProcessElement中必须先 claim 再处理,未经 claim 就处理会导致错误输出;claim 成功则必须处理完整块,失败则必须立即返回且不再产生任何输出;TrySplit(fraction):按剩余工作比例把当前 restriction 切分为 primary(当前正在执行的工作)与 residual(切分出去的工作),供动态分片与自动伸缩使用;- 特别地,
TrySplit(0)用于自检查点(self-checkpointing):返回"无剩余工作的 primary + 包含全部剩余工作的 residual",同时将 tracker 标记为完成,保证 checkpoint 期间不丢数据。
LockRTracker(lock.go)为 RTracker 提供线程安全封装,使动态分片所需的并发方法调用安全成立。
四、Java SDK:基于注解的 Splittable DoFn
Java SDK 中,Splittable DoFn 是一个 继承了 DoFn 的类,通过方法级注解声明 SDF 语义,需要实现的注解包括:
@ProcessElement:标注对输入PCollection每个元素执行的入口方法(ParDo中处理每个元素);@GetInitialRestriction:生成该元素的初始 restriction 集合;@GetRestrictionCoder:返回 restriction 类型的Coder。Splittable DoFn 把输入集合划分为可在不同 worker 间并行处理的小块(restriction),每个 restriction 都需要通过 coder 在 worker 间序列化/反序列化;@SplitRestriction:把一个 restriction 拆分为多个子 restriction,供并行处理。
课程示例位于 java-example/Task.java,其核心 SplitLinesFn 如下:
static class SplitLinesFn extends DoFn<String, KV<Long, String>> {
private static final Integer batchSize = 5;
@ProcessElement
public void process(ProcessContext c, RestrictionTracker<OffsetRange, Long> tracker) {
String[] words = c.element().split(" ");
for (long i = tracker.currentRestriction().getFrom(); tracker.tryClaim(i); ++i) {
c.output(KV.of(i, words[(int) i]));
}
}
@GetInitialRestriction
public OffsetRange getInitialRestriction(@Element String e) {
return new OffsetRange(0, e.split(" ").length);
}
@GetRestrictionCoder
public Coder<OffsetRange> getRestrictionCoder() {
return OffsetRange.Coder.of();
}
@SplitRestriction
public void splitRestriction(@Element String input, @Restriction OffsetRange restriction, OutputReceiver<OffsetRange> receiver) throws Exception {
long start = restriction.getFrom();
long size = restriction.getTo();
long splitSizeBytes = size / batchSize;
while (start < size) {
long splitEnd = start + splitSizeBytes;
if (splitEnd >= size) {
splitEnd = size;
}
receiver.output(new OffsetRange(start, splitEnd));
start = splitEnd;
}
}
}
示例的用法是把 SplitLinesFn 直接套在 Create.of(...) 产生的字符串元素上:input.apply(ParDo.of(new SplitLinesFn()))。@GetInitialRestriction 把整个句子切分成词的索引区间 [0, words.length);@SplitRestriction 按 batchSize=5 把这个区间再切成若干子区间;@ProcessElement 则通过 tracker.tryClaim(i) 逐个认领词索引并输出 KV<Long, String>。
底层契约:Java 的抽象类 RestrictionTracker.java 明确定义了 SDF 的约束(见 RestrictionTracker.java):
tryClaim(position):claim 成功则DoFn必须执行整个工作块;claim 失败则@ProcessElement必须返回ProcessContinuation.stop,且不得再执行任何工作或发射输出(在首次调用本方法之前也不允许发射输出),同时checkDone()必须成功;- 每个被认领的位置必须是一个合法的 split point;
currentRestriction():返回描述当前调用完整工作范围(含已完成部分)的 restriction,它可能因并发调用trySplit(double)等而动态更新。
配套的 OffsetRangeTracker.java 与 OffsetRange.Coder.of() 提供了对 [from, to) 偏移区间的标准 tracker 与编码实现,可直接复用。
五、Python SDK:基于 RestrictionProvider 的 Splittable DoFn
Python SDK 中,Splittable DoFn 是一个继承 DoFn 的类,在 process 方法中通过 DoFn.RestrictionParam(...) 注入 restriction provider。需要实现的 provider 方法包括:
create_tracker:创建 tracker 对象,用于跟踪一个 bundle 内元素处理进度;initial_restriction:为输入元素创建初始 restriction;restriction_size:返回 restriction 的大小;split:把 restriction 拆分为更小的子 restriction,供并行处理;process:用户自定义处理函数,对PCollection中每个元素执行,在ParDo中对每个输入元素产生零个或多个输出元素。
课程示例位于 python-example/task.py,核心代码如下:
class SplitLinesFn(beam.RestrictionProvider):
def create_tracker(self, restriction):
return restriction_trackers.OffsetRestrictionTracker(restriction)
def initial_restriction(self, element):
return OffsetRange(0, len(element.split()))
def restriction_size(self, element, restriction):
return restriction.size()
def split(self, element, restriction):
start = restriction.start
size = restriction.stop - restriction.start
split_size_bytes = size // 5
while start < restriction.stop:
split_end = start + split_size_bytes
if split_end >= restriction.stop:
split_end = restriction.stop
yield OffsetRange(start, split_end)
start = split_end
class MyFileSource(beam.DoFn):
def process(self, element, restriction_tracker=DoFn.RestrictionParam(SplitLinesFn())):
input = element.split()
cur = restriction_tracker.current_restriction().start
while restriction_tracker.try_claim(cur):
yield cur, input[cur]
cur += 1
with beam.Pipeline() as p:
lines = (p | 'Create' >> beam.Create(["Lorem Ipsum is simply dummy text ..."])
| beam.ParDo(MyFileSource())
| 'Print' >> beam.Map(print))
注意 process 中 DoFn.RestrictionParam(SplitLinesFn()) 这一写法:它把 restriction provider 绑定到该 DoFn,运行框架会据此完成初始 restriction、split、tracker 创建等 SDF 生命周期管理。
底层契约:Python 的 restriction_trackers.py 提供了 OffsetRange(start/stop 半开区间,size() 返回区间大小,split() 支持按期望分片大小切分并避免末尾碎片)与 OffsetRestrictionTracker(restriction_trackers.py)。后者的 try_claim(position) 语义与 Java/Go 一致:
- claim 位置必须严格递增、且不能小于区间起点,否则抛出
ValueError; - 若
start <= position < stop则 claim 成功并更新_current_position; check_done()校验整个区间是否全部被认领,未被认领的剩余工作会导致校验失败。
六、三 SDK 实现方式速览
| 阶段 | Go | Java | Python |
|---|---|---|---|
| 载体 | struct + 方法 | DoFn 子类 + 注解 |
DoFn + RestrictionProvider |
| 初始 restriction | CreateInitialRestriction |
@GetInitialRestriction |
initial_restriction |
| 切分 restriction | SplitRestriction |
@SplitRestriction |
split |
| restriction 大小 | RestrictionSize |
(可选实现) | restriction_size |
| 创建 tracker | CreateTracker → sdf.LockRTracker |
@ProcessElement 注入 RestrictionTracker |
create_tracker |
| 元素处理 | ProcessElement(ctx, rt, ...) |
@ProcessElement + tryClaim 循环 |
process + try_claim 循环 |
| restriction 编码 | 框架自动(注册类型) | @GetRestrictionCoder |
框架自动 |
三者共享同一套思想:初始 restriction → 递归 split → 每块配 tracker → tryClaim 逐块处理 → checkDone 收尾,区别仅在 SDK 的编程模型表达方式。
七、动手练习:用 Splittable DoFn 读取数据库
课程单元在 description.md 末尾给出了一项 playground 练习任务:
为处理大数据实现 Splittable DoFn,例如针对数据库。请编写一个使用 Apache Beam 通过 Splittable DoFn 读取数据库的程序。
结合前三节的实现范式,完成该练习只需把"restriction"从字节区间替换为数据库查询区间,并复用同一套骨架:
- 定义 restriction:使用自定义类型表示查询范围,例如主键区间
[startKey, endKey)或行号区间[startOffset, endOffset); - 实现初始 restriction 与 split:
initial_restriction返回全表/全分区范围,split按固定批次大小(如每 1000 行)切分子区间,从而让多个 worker 并行扫描不同区间; - 实现 tracker 与 process:在
process/ProcessElement中按当前 restriction 构造带WHERE 主键 BETWEEN start AND end的查询,通过try_claim逐段推进游标,每 claim 一段便读取该段记录并发射; - 利用动态分片:当某个 worker 处理过慢时,运行框架可通过
trySplit将其剩余区间切分给空闲 worker,实现负载均衡与自动伸缩。
你可以直接在 tour-of-beam 的 playground 中分别选择 Go / Java / Python 的 splittable-dofn 任务(对应 go-example/main.go、java-example/Task.java、python-example/task.py)运行并改写,这三个示例均可直接作为改造为数据库读取的起点。
八、小结
- Splittable DoFn 是 Apache Beam 中处理超大输入、打破单 worker 瓶颈的核心 transform:它把输入源动态切分为独立块并交给多个 worker 并行处理,分片数量随数据规模与可用资源动态调整;
- 它适用于文件、数据库等可高效切分的数据源,通过
Restriction(工作范围)、Split(切分产物)、RestrictionTracker(进度跟踪与动态分片)三个抽象协同工作; - 三个 SDK 的编程表达不同(Go 的 struct 方法、Java 的注解、Python 的
RestrictionProvider),但底层契约一致:tryClaim 必须先于工作执行、claim 成功必须处理完整块、claim 失败必须立即停止且无输出、结束时 checkDone 校验,trySplit支撑动态分片与自检查点; - 从源码看,Java 的 RestrictionTracker.java、Go 的 sdf.go 与 Python 的 restriction_trackers.py 分别把上述契约固化在 SDK 层,而 tour-of-beam 的 splittable 单元 则提供了可直接运行的三语言演练场——用它们把"读取数据库"这类真实的大数据 I/O 场景落地,正是 SDF 价值的最佳体现。