Apache Beam Splittable DoFn 实战指南:突破单 Worker 并行瓶颈的 Java、Python、Go 三 SDK 完整实现与原理剖析

原创2026-10-09 17:28:151,956 阅读

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"从字节区间替换为数据库查询区间,并复用同一套骨架:

  1. 定义 restriction:使用自定义类型表示查询范围,例如主键区间 [startKey, endKey) 或行号区间 [startOffset, endOffset);
  2. 实现初始 restriction 与 split:initial_restriction 返回全表/全分区范围,split 按固定批次大小(如每 1000 行)切分子区间,从而让多个 worker 并行扫描不同区间;
  3. 实现 tracker 与 process:在 process/ProcessElement 中按当前 restriction 构造带 WHERE 主键 BETWEEN start AND end 的查询,通过 try_claim 逐段推进游标,每 claim 一段便读取该段记录并发射;
  4. 利用动态分片:当某个 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 价值的最佳体现。
登录后查看全文
beam