Apache Beam Splittable DoFn(SDF):新一代 I/O 连接器开发范式

原创2026-10-11 16:03:001,911 阅读

Apache Beam Splittable DoFn(SDF):新一代 I/O 连接器开发范式

导读

Apache Beam 官方于 2.25.0 版本正式宣布 Splittable DoFn(SDF) 在 Python、Java、Go 三大 SDK 中全面可用(见 官方公告)。SDF 是 DoFn 的泛化,它让一个普通 DoFn 获得传统 Source 的核心能力(拆分、动态工作再平衡、并行处理),同时保留 DoFn 的语法简洁性、灵活性与模块化特性。本文以官方公告为骨架,结合仓库源码与编程指南,系统讲解 SDF 的设计动机、三大优势、核心执行机制(restriction、tracker、watermark estimator),并给出 Java / Python / Go 的实操示例与仓库中的真实应用案例,帮助读者掌握用 SDF 构建新一代 I/O 连接器的方法。

1. 公告背景:SDF 的设计起源与定位

SDF 并非 2.25.0 才提出。早在 2017 年,Beam 社区便通过 Splittable DoFn 设计文档 提出将 SDF API 作为构建 I/O 连接器的新推荐方式。其核心思想是:

Splittable DoFn 是 DoFn 的泛化,赋予 DoFn 以 Source 的核心能力,同时保留 DoFn 的语法、灵活性、模块化和易编码性。

因此,开发者可以用更简单、更可复用的代码开发复杂 I/O 连接器。公告同时强调:SDF 现已准备就绪并附带上述全部改进,官方推荐将其作为构建新 I/O 连接器的方式,并提供了大量通用工具类(如常见类型的 RestrictionTracker 与 WatermarkEstimator)帮助开发者快速上手。

2. SDF 相对传统 Source API 的三大优势

公告明确指出,SDF 相对现有 UnboundedSource 与 BoundedSource 有三方面核心优势:

2.1 统一 API 同时覆盖有界与无界场景

SDF 提供一套统一的 API 处理有界(bounded)与无界(unbounded)两种情况。传统方案中,BoundedSource 与 UnboundedSource 是两套并行的接口,各有各的 split、Reader、CheckpointMark 机制;SDF 则通过元素-限制(element-restriction)对来抽象工作量,用同一套注解与回调在不同粒度上表达“有界/无界”。

2.2 支持运行时动态读取 source descriptor(以 Kafka 为例)

SDF 支持动态地从 source descriptor 读取。以 KafkaIO 为例:

  • 传统 UnboundedSource / BoundedSource:必须在管道构建期就指定要读取的 topic 与 partition,执行期无法把 topic/partition 作为输入传入;
  • SDF:将 KafkaSourceDescriptor(封装 topic、partition、起始/结束 offset 或时间)作为输入元素,在运行期即可动态决定读取范围,这是 SDF 内置能力。

在仓库中,ReadFromKafkaDoFn.java 的 @GetInitialRestriction 方法正是对元素(KafkaSourceDescriptor)动态计算 OffsetRange(从配置的起始 offset / 起始时间 / 消费者当前位置推算起始,以 Long.MAX_VALUE 或结束 offset / 结束时间作为上限),完美印证了这一设计。

2.3 可在管道任意位置使用且具备拆分能力

传统 UnboundedSource / BoundedSource 必须作为管道根节点才能获得拆分策略带来的性能收益,这限制了许多真实场景。而 SDF 可以作为管道中任意一个节点自由使用,同时具备拆分能力。

在 programming-guide.md 中对此有更形象的说明:一个热门用例是“先从消息队列读取文件名,再解析这些文件”。传统做法要么把队列逻辑和文件读取逻辑写进同一个 I/O 连接器(增加复杂度),要么用普通 DoFn 读文件(牺牲性能);有了 SDF,既可保持模块化,又能维持传统 I/O 连接器的性能。

3. SDF 基础:核心组件与执行流程

SDF 的完整设计在 Splittable DoFn 编程指南章节中有系统阐述,以下是其核心骨架。

3.1 执行四步流程

执行一个 SDF 遵循以下步骤:

  1. 每个元素与一个 restriction 配对(例如文件名与表示整个文件的 offset 范围配对);
  2. 每个“元素+restriction”对被拆分(例如 offset 范围被切分成更小的片段);
  3. runner 将“元素+restriction”对重新分配到多个 worker;
  4. “元素+restriction”对被并行处理(例如读取文件)。在此过程中,该对可以自行暂停处理,或进一步拆分成更多“元素+restriction”对。

3.2 五个核心组件

一个基本 SDF 由三部分组成;若需控制 watermark(尤其流式管道),还需两个组件:

组件 作用 Java Python Go
Restriction(限制) 用户自定义对象,表示某元素的一个工作子集。例如 OffsetRange 表示 offset 位置范围 OffsetRange OffsetRange(restriction_trackers) offsetrange.Restriction
RestrictionProvider(限制提供者) 让 SDF 作者覆写默认的拆分与 sizing 实现 即 DoFn 本身 独立 RestrictionProvider 类型 即 DoFn
RestrictionTracker(限制追踪器) 追踪处理过程中 restriction 的哪一部分已完成 OffsetRangeTracker、GrowableOffsetRangeTracker、ByteKeyRangeTracker OffsetRestrictionTracker offsetrange.Tracker(配合 LockRTracker)
WatermarkEstimatorProvider 定义如何初始化 watermark 状态、创建 watermark estimator 即 DoFn 独立 WatermarkEstimatorProvider 即 DoFn
WatermarkEstimator(水位线估计器) 在“元素+restriction”对处理期间追踪 watermark WatermarkEstimators.Manual、.MonotonicallyIncreasing、.WallTime ManualWatermarkEstimator、MonotonicWatermarkEstimator、WalltimeWatermarkEstimator TimestampObservingEstimator、WalltimeWatermarkEstimator

3.3 有界与无界的界定

定义 SDF 时,必须选择有界(默认)或无界,并定义元素的初始 restriction 的初始化方式。区别取决于工作量如何表示:

  • 有界 DoFn:元素所代表的工作量事先明确且有终点。典型例子是文件或一组文件;
  • 无界 DoFn:工作量没有特定终点,或事先未知。典型例子是 Kafka topic 或 PubSub topic。

Java 中可用 @UnboundedPerElement 或 @BoundedPerElement 注解 DoFn;Python 中用 @unbounded_per_element 注解。

3.4 一个基础 SDF:Java / Python / Go 对照

公告引用编程指南推荐读者动手实践。下面是仓库中 Snippets.java 与 snippets.py 的“读取文件按词输出”基础示例:

Java(FileToWordsFn)

@BoundedPerElement
private static class FileToWordsFn extends DoFn<String, Integer> {
  @GetInitialRestriction
  public OffsetRange getInitialRestriction(@Element String fileName) throws IOException {
    return new OffsetRange(0, new File(fileName).length());
  }

  @ProcessElement
  public void processElement(
      @Element String fileName,
      RestrictionTracker<OffsetRange, Long> tracker,
      OutputReceiver<Integer> outputReceiver) throws IOException {
    RandomAccessFile file = new RandomAccessFile(fileName, "r");
    seekToNextRecordBoundaryInFile(file, tracker.currentRestriction().getFrom());
    while (tracker.tryClaim(file.getFilePointer())) {
      outputReceiver.output(readNextRecord(file));
    }
  }

  // Providing the coder is only necessary if it can not be inferred at runtime.
  @GetRestrictionCoder
  public Coder<OffsetRange> getRestrictionCoder() {
    return OffsetRange.Coder.of();
  }
}

Python(FileToWordsFn)

class FileToWordsRestrictionProvider(beam.transforms.core.RestrictionProvider):
  def initial_restriction(self, file_name):
    return OffsetRange(0, os.stat(file_name).st_size)

  def create_tracker(self, restriction):
    return beam.io.restriction_trackers.OffsetRestrictionTracker()

class FileToWordsFn(beam.DoFn):
  def process(
      self,
      file_name,
      # Alternatively, we can let FileToWordsFn itself inherit from
      # RestrictionProvider, implement the required methods and let
      # tracker=beam.DoFn.RestrictionParam() which will use self as
      # the provider.
      tracker=beam.DoFn.RestrictionParam(FileToWordsRestrictionProvider())):
    with open(file_name) as file_handle:
      file_handle.seek(tracker.current_restriction.start())
      while tracker.try_claim(file_handle.tell()):
        yield read_next_record(file_handle)

  # Providing the coder is only necessary if it can not be inferred at runtime.
  def restriction_coder(self):
    return ...

Go(splittableDoFn,出自编程指南)

func (fn *splittableDoFn) CreateInitialRestriction(filename string) offsetrange.Restriction {
	return offsetrange.Restriction{
		Start: 0,
		End:   getFileLength(filename),
	}
}

func (fn *splittableDoFn) CreateTracker(rest offsetrange.Restriction) *sdf.LockRTracker {
	return sdf.NewLockRTracker(offsetrange.NewTracker(rest))
}

func (fn *splittableDoFn) ProcessElement(rt *sdf.LockRTracker, filename string, emit func(int)) error {
	file, err := os.Open(filename)
	if err != nil {
		return err
	}
	offset, err := seekToNextRecordBoundaryInFile(file, rt.GetRestriction().(offsetrange.Restriction).Start)
	if err != nil {
		return err
	}
	for rt.TryClaim(offset) {
		record, newOffset := readNextRecord(file)
		emit(record)
		offset = newOffset
	}
	return nil
}

三个版本的关键模式一致:ProcessElement 中每次只处理 tryClaim 成功的位置,成功后才读取、产出并推进 offset。

3.5 初始拆分:加速初始并行度

上述基础 SDF 已支持 runner 发起的拆分(动态工作再平衡)。若要提高初始并行化的速度,或 runner 不支持 runner 发起的拆分,官方建议提供一组初始拆分,把大 restriction 预先切成小块(如 64 MiB 一个):

void splitRestriction(
    @Restriction OffsetRange restriction, OutputReceiver<OffsetRange> splitReceiver) {
  long splitSize = 64 * (1 << 20);
  long i = restriction.getFrom();
  while (i < restriction.getTo() - splitSize) {
    // Compute and output 64 MiB size ranges to process in parallel
    long end = i + splitSize;
    splitReceiver.output(new OffsetRange(i, end));
    i = end;
  }
  // Output the last range
  splitReceiver.output(new OffsetRange(i, restriction.getTo()));
}
class FileToWordsRestrictionProvider(beam.transforms.core.RestrictionProvider):
  def split(self, file_name, restriction):
    # Compute and output 64 MiB size ranges to process in parallel
    split_size = 64 * (1 << 20)
    i = restriction.start
    while i < restriction.end - split_size:
      yield OffsetRange(i, i + split_size)
      i += split_size
    yield OffsetRange(i, restriction.end)

4. 进阶机制:sizing、checkpoint、拆分、watermark 与 drain

编程指南将 SDF 进阶能力分为若干主题,公告虽未逐条展开,但这些是 SDF 成为“新一代 I/O 连接器范式”的底层支撑:

4.1 Sizing 与 progress

Sizing 与 progress 用于在执行期间告知 runner,让 runner 对“拆哪个 restriction、如何并行化工作”做出智能决策。默认使用 restriction tracker 对“剩余工作量”的估计(若不可用则假设所有 restriction 成本相同);SDF 作者可在 restriction provider 中覆写(注意 sizing 方法可能在 bundle 处理期间被并发调用)。例如在 Go 中覆写 RestrictionSize 返回加权大小:

func (fn *splittableDoFn) RestrictionSize(filename string, rest offsetrange.Restriction) float64 {
	weight := float64(1)
	if strings.Contains(filename, "expensiveRecords") {
		weight = 2
	}
	return weight * (rest.End - rest.Start)
}

4.2 用户发起的 checkpoint

有些 I/O 无法在单个 bundle 的生命周期内完成一个 restriction 所需的全部数据(常见于无界 restriction,也可能出现在有界 restriction:例如数据尚未就绪、或源系统限流)。SDF 可以发出“当前 restriction 还没处理完”的信号,并可附带建议的恢复时间(runner 会尽量尊重但不保证),从而让执行继续推进到“有活可干”的 restriction 上,提升资源利用率。

4.3 Runner 发起的 split

runner 可以在任何时刻尝试拆分正在处理的 restriction,从而:暂停该 restriction 的处理以执行其他工作(无界 restriction 常用,用于限制输出量或改善延迟),或把 restriction 一分为二以提升系统内并行度。不同 runner(如 Dataflow、Flink、Spark)在批处理与流式执行下有不同的拆分策略。因此编写处理循环时必须以 tryClaim 的返回值为准,不能假定能一直处理到 restriction 末尾——编程指南专门给出了反例(把 end 存为局部变量、循环里无视 tryClaim 返回值直接产出)来说明这样写的风险。

4.4 Watermark 估计

默认 watermark estimator 不产生 watermark 估计,输出 watermark 仅由上游 watermark 的最小值决定。SDF 可以通过为“该元素+restriction 对未来所有输出”指定下界来推进输出 watermark:runner 取“所有上游 watermark 的最小值”与“每对报告 watermark 的最小值”作为输出 watermark。报告 watermark 必须随 bundle 边界单调递增;当某对停止处理时,其 watermark 不再参与计算。若 SDF 输出带时间戳的记录,应提供配置项让使用者选择 watermark estimator;在 watermark 之前产出的数据可能被视为迟到数据。

编程指南区分了两类 watermark estimator:timestamp observing(用每条输出的时间戳推算)与external clock observing(用与输出无关的时钟,如机器本地时钟或外部服务暴露的时钟)控制 watermark。

4.5 Draining 时的截断(truncate)

支持 draining 管道的 runner 需要能“排干”SDF,否则管道可能永远不会停止。默认行为是:有界 restriction 处理完剩余部分,无界 restriction 在下一个 SDF 发起的 checkpoint 或 runner 发起的 split 处结束。SDF 作者可在 restriction provider 上定义相应方法覆写默认行为。Go 中特别提示:drain 开始并触发 truncate restriction 后,sdf.ProcessContinuation 将不再被重新调度。

4.6 Bundle finalization

Bundle finalization 让 DoFn 通过注册回调执行副作用:回调在 runner 确认输出已持久化后被调用(例如消息队列在数据被摄入管道后需要确认消息)。该能力不限于 SDF,但 SDF 是主要使用场景。

5. 真实世界的 SDF 应用:仓库源码印证

公告末尾列出了一批真实 SDF 示例。以下结合当前仓库源码逐一说明,读者可直接打开对应文件对照研读。

5.1 Java 示例

Kafka 连接器:ReadFromKafkaDoFn.java

Apache Kafka 的 I/O 连接器。它是 SDF 动态 source descriptor 能力的典型代表:

  • @GetInitialRestriction 对 KafkaSourceDescriptor 元素动态计算 OffsetRange:根据 startReadOffset / startReadTime / 消费者当前位置决定起始 offset,根据 stopReadOffset / stopReadTime 决定结束(未指定则为 Long.MAX_VALUE,即无界);
  • @GetInitialWatermarkEstimatorState 与 @NewWatermarkEstimator 实现 watermark 估计:以当前元素时间戳为初始状态,通过可配置的 createWatermarkEstimatorFn 创建估计器;
  • @NewTracker 返回 OffsetRangeTracker;当 restriction 上界为 Long.MAX_VALUE 时,使用缓存的 KafkaLatestOffsetEstimator 做 backlog 估算;
  • @GetSize 结合平均记录大小与剩余工作量估算 restriction 大小,供 runner 做拆分决策。

从源码结构看,Bounded 与 Unbounded 两个子类共用同一套 SDF 骨架,进一步印证了“统一 API 同时覆盖有界与无界”的设计目标。

Watch:Watch.java

使用轮询函数为每个输入产生不断增长的输出集合,直到满足“按输入”的终止条件。适合监控目录、外部系统变化等场景。

Parquet:ParquetIO.java

Apache Parquet(开源列式存储格式)的 I/O 连接器,以 SDF 实现按文件或按行组的拆分读取。

HL7v2:HL7v2IO.java

HL7v2 消息(组织内部事件信息的临床消息格式,属于 Google Cloud Healthcare API)的 I/O 连接器。其 ListHL7v2MessagesFn 展示了 SDF 在时间范围上的应用:

  • @GetInitialRestriction 通过客户端查询该 store 的最早/最晚发送时间,构造 OffsetRange(from, to + 1ms)(与 OffsetRangeTracker 的 [from, to) 语义对齐);
  • @SplitRestriction 按 initialSplitDuration(默认 DEFAULT_DESIRED_SPLIT_DURATION)把时间范围拆分成多段,并打印拆分数目日志;
  • @ProcessElement 以 RestrictionTracker<OffsetRange, Long> 追踪时间范围,逐段列出消息。

BoundedSource wrapper:Read.java

把现有 BoundedSource 实现包装成 splittable DoFn 的包装器。从源码看,其建模方式是把元素视为原始 source、restriction 视为 sub-source,从而可以反复拆分 sub-source 而输入仍是 “source” 对象。@SplitRestriction 调用 restriction.getEstimatedSizeBytes 估算大小并设定期望 chunk 大小(估算值不可用时默认 64 MiB;否则按 1000 * sqrt(estimatedSize) 且下限 1 MiB 推算期望块大小),再调用 restriction.split(desiredChunkSize, options) 产出拆分结果。restriction coder 使用 SnappyCoder.of(SerializableCoder...) 压缩序列化。

UnboundedSource wrapper:Read.java

把现有 UnboundedSource 实现包装成 splittable DoFn 的包装器,让传统无界 source 也能享受 SDF 的拆分与模块化能力。

5.2 Python 示例

BoundedSourceWrapper:iobase.py

把现有 BoundedSource 包装为 splittable DoFn 的包装器。仓库中的实现是 _SDFBoundedSourceRestrictionProvider 与 SDFBoundedSourceReader:

  • _SDFBoundedSourceRestrictionProvider 是 RestrictionProvider 子类:initial_restriction 从 BoundedSource.get_range_tracker(None, None) 构造 _SDFBoundedSourceRestriction;split 通过 Read.get_desired_chunk_size 估算期望 chunk 大小(估算不可用时会触发 NotImplementedError 兜底)再调用 source.split;create_tracker 返回 _SDFBoundedSourceRestrictionTracker;
  • SDFBoundedSourceReader 是一个 PTransform,内部 SDFBoundedSourceDoFn.process 以 core.DoFn.RestrictionParam(_SDFBoundedSourceRestrictionProvider()) 声明 SDF 参数,并调用 restriction.source().read(restriction.range_tracker()) 读取数据。文档注释特别提醒:该 transform 只能在 beam_fn_api 开启时使用。

5.3 Go 示例

textio.ReadSdf:textio.go

textio.ReadSdf 是 Read 的一个变体,用 Splittable DoFn 实现文本文件读取。源码中:

  • readBaseFn.CreateTracker 用 sdf.NewLockRTracker(offsetrange.NewTracker(rest)) 返回 *sdf.LockRTracker(配合 LockRTracker 保证并发安全);
  • readFn 与 readWNameFn 的 ProcessElement 接收 *sdf.LockRTracker、fileio.ReadableFile 与 emit 函数,逐段 TryClaim 并产出内容(readWNameFn 额外产出文件名)。

5.4 现有 I/O 的迁移路径

公告还给出明确的迁移指引:官方已把 UnboundedSource 和 BoundedSource 的实现包装成 Splittable DoFn(即上述 Java 的 Read.BoundedSourceAsSDFWrapperFn / UnboundedSourceAsSDFWrapperFn、Python 的 SDFBoundedSourceReader、Go 的 textio.ReadSdf),但依然鼓励开发者把 UnboundedSource / BoundedSource 改造成真正的 SDF 实现以获取更多性能收益。

6. 上手建议与注意事项

  1. 从编程指南入手:完整学习 SDF 章节(programming-guide.md),其中包含 Java/Python/Go 三语种的配套代码(Java 在 Snippets.java,Python 在 snippets.py,Go 在 textio.go 与 sdks/go/examples/snippets/)。
  2. 复用内置组件:优先使用 SDK 内置的 OffsetRangeTracker、GrowableOffsetRangeTracker、ByteKeyRangeTracker 与各类 WatermarkEstimator,减少自研成本。
  3. 正确编写处理循环:始终以 tryClaim 的返回值为准推进,不要在局部变量里缓存 restriction 末端,否则 runner 发起 split 时可能产出越界数据。
  4. 按需实现进阶回调:需要初始并行度时提供 splitRestriction;需要精确调度时覆写 sizing;流式场景务必配置 watermark estimator 并对输出打时间戳。
  5. 环境前提:Python 的 SDFBoundedSourceReader 依赖 beam_fn_api 开启;无界 SDF 与 watermark/checkpoint 行为受 runner 支持程度影响,部署前请对照所选 runner(Dataflow、Flink、Spark 等)的文档确认。

从公告发布(2.25.0,2020-12-14)到当前仓库代码,SDF 已从“可用”成长为 Beam I/O 生态的事实标准:新连接器以 SDF 为默认实现方式,旧连接器通过 wrapper 平滑过渡。无论你是连接器作者、还是想在管道中间节点直接做带拆分能力的处理,SDF 都是值得掌握的核心能力。

登录后查看全文
beam