Apache Beam Splittable DoFn(SDF):新一代 I/O 连接器开发范式
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 遵循以下步骤:
- 每个元素与一个 restriction 配对(例如文件名与表示整个文件的 offset 范围配对);
- 每个“元素+restriction”对被拆分(例如 offset 范围被切分成更小的片段);
- runner 将“元素+restriction”对重新分配到多个 worker;
- “元素+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. 上手建议与注意事项
- 从编程指南入手:完整学习 SDF 章节(programming-guide.md),其中包含 Java/Python/Go 三语种的配套代码(Java 在 Snippets.java,Python 在 snippets.py,Go 在 textio.go 与
sdks/go/examples/snippets/)。 - 复用内置组件:优先使用 SDK 内置的
OffsetRangeTracker、GrowableOffsetRangeTracker、ByteKeyRangeTracker与各类WatermarkEstimator,减少自研成本。 - 正确编写处理循环:始终以
tryClaim的返回值为准推进,不要在局部变量里缓存 restriction 末端,否则 runner 发起 split 时可能产出越界数据。 - 按需实现进阶回调:需要初始并行度时提供
splitRestriction;需要精确调度时覆写 sizing;流式场景务必配置 watermark estimator 并对输出打时间戳。 - 环境前提: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 都是值得掌握的核心能力。