Apache Beam 流式输入连接器深度解读:Java / Python 输入源全景对比与源码级实战

原创2026-10-11 15:58:541,688 阅读

Apache Beam 流式输入连接器深度解读:Java / Python 输入源全景对比与源码级实战

本文基于 Apache Beam 仓库中的官方博客 review-input-streaming-connectors.md 展开,系统梳理 Beam 在流式(Streaming)场景下可用的输入连接器(Input Connectors),并与 Apache Spark 的流式输入方案逐项对比。读者读完后将掌握:Beam Java / Python SDK 中文件系统、对象存储、消息队列三类流式输入源的选型与配置方法,理解 KafkaIO、KinesisIO、PubsubIO 等核心连接器的源码级使用细节,以及如何借助 Read Transforms 自定义流式数据源。

为什么专门关注“流式输入”连接器

在批处理场景下,你可以从任意数据源加载数据,包括各类数据库系统——即便没有针对性的 SDK,通常也能借助 JDBC 驱动直接读取。但在流式场景下,情况要复杂得多:可用的数据源类型明显更少,实现一个正确的流式数据管道也更富挑战性。因此,本文以流式输入(streaming input)为核心,对比 Apache Beam 与 Apache Spark 两大生态在这方面的现状与差异。

Apache Beam 提供统一的批流编程模型,拥有官方 Java SDK 和多个执行引擎(Runner),各 Runner 的能力差异可以参考仓库中的 能力矩阵文档。在大多数情况下,用 Java 或 Scala 编写的既有 Beam 管道可以借助 Spark Runner 较为轻松地迁移到 Spark 环境运行。

Spark 本身使用 Scala 编写、提供 Java API,其源码编译为 Java 字节码并在 JVM 上执行,因此 Scala 与 Java 天然互操作,也就能原生兼容 Java 类库(反之亦然)。Spark 提供两种流式方案:

  • DStreams(Discretized Streaming):一种基础抽象,表示一系列 RDD(弹性分布式数据集)的连续流;
  • Structured Streaming:较晚引入(首个 alpha 版本随 Spark 2.1.0 发布),其编程模型把实时数据持续追加到一张“表”结构中。

Spark Structured Streaming 支持文件源(本地文件系统以及 Cloud Storage、S3 等 HDFS 兼容系统)和 Kafka 作为流式输入;DStreams 则内置了面向 Kafka、Flume 等第三方服务的连接器,其余连接器可通过链接外部依赖获得。

Java 生态下的流式输入连接器对比

下表汇总了 Beam 与 Spark DStreams 在 Java 下的主要流式输入连接器:

类别 子类(URI 协议) Apache Beam Apache Spark DStreams
文件系统 本地(file://) TextIO textFileStream(Spark 将大多数 Unix 系统视为 HDFS 兼容,但路径需对所有节点可访问)
文件系统 HDFS(hdfs://) FileIO + HadoopFileSystemOptions HdfsUtils
对象存储 Cloud Storage(gs://) FileIO + GcsOptions hadoopConfiguration + textFileStream
对象存储 S3(s3://) FileIO + S3Options 同上
消息队列 Kafka KafkaIO spark-streaming-kafka
消息队列 Kinesis KinesisIO spark-streaming-kinesis
消息队列 Cloud Pub/Sub PubsubIO spark-streaming-pubsub(来自 Apache Bahir)
其他 自定义接收器 Read Transforms receiverStream

文件与对象存储:TextIO / FileIO 体系

Beam 读取本地文本文件的入口是 TextIO.read(),其源码位于 TextIO.java,典型用法为:

PCollection<String> lines = p.apply(TextIO.read().from("/local/path/to/file.txt"));

对于 HDFS、Cloud Storage、S3 等分布式存储,Beam 使用 FileIO 配合各存储系统的 PipelineOptions 完成配置:

  • HDFS:FileIO + HadoopFileSystemOptions,相关选项注册器见 HadoopFileSystemOptionsRegistrar.java;
  • Cloud Storage:FileIO + GcsOptions,通过 gs:// URI 访问;
  • S3:FileIO + S3Options,通过 s3:// URI 访问(仓库中同时保留了 aws 与 aws2 两套实现,选用时注意对应版本)。

在流式场景下,这些文件系统连接器配合 Runner 对 unbounded 数据源的持续监听机制,即可实现对持续写入文件目录的数据进行增量读取。

消息队列:KafkaIO

KafkaIO 是 Beam 官方维护的 Kafka 无界读取与写入连接器,实现位于 KafkaIO.java。其源码类注释给出了一个完整的最小读取配置:

pipeline
  .apply(KafkaIO.<Long, String>read()
     .withBootstrapServers("broker_1:9092,broker_2:9092")
     .withTopic("my_topic")  // 多 topic 请使用 withTopics(List<String>)
     .withKeyDeserializer(LongDeserializer.class)
     .withValueDeserializer(StringDeserializer.class)
     // 以上四项为必填配置,返回 PCollection<KafkaRecord<Long, String>>
     // 以下均为可选设置:
     .withConsumerConfigUpdates(ImmutableMap.of("group.id", "my_beam_app_1"))
     // 事件时间与水位线策略:默认 withProcessingTime();
     // 对带 CreateTime 时间戳的 topic 可改用 withCreateTime(),或显式使用 withLogAppendTime()
     .withLogAppendTime()
     // 只读取 Kafka 已提交消息(见方法文档)
     .withReadCommitted()
     // 管道消费的 offset 可在 finalize 阶段提交回 Kafka
     .commitOffsetsInFinalize()
     // 可在运行时决定是否停止读取某 TopicPartition 的可序列化函数
     .withCheckStopReadingFn(new SerializedFunction<TopicPartition, Boolean>() {})
     // 将解析失败的坏消息路由到备用 sink 的错误处理模式
     .withBadRecordErrorHandler(errorHandler)
     // 若不需要 Kafka 元数据,可去掉它
     .withoutMetadata() // PCollection<KV<Long, String>>
  )
  .apply(Values.<String>create()) // PCollection<String>

几个值得留意的源码细节:

  • Coder 推断:Beam Runner 需要 Coder 来物化键值对象。多数情况下 Coder 会从反序列化器类型自动推断;推断失败时,可通过 withKeyDeserializerAndCoder(Class, Coder) 与 withValueDeserializerAndCoder(Class, Coder) 显式指定。
  • 动态读取:KafkaIO 支持“动态读”——通过 WatchForKafkaTopicPartitions 监控 topic/partition 的新增或删除,再由 ReadFromKafkaDoFn 读取每个 KafkaSourceDescriptor,从而应对“topic/partition 被新增/删除”以及“被移除后又重新出现”等场景;结合 checkStopReadingFn 还能处理“停止后重新读取”的诉求。源码注释也明确指出这类场景下存在竞态条件(可能丢失重新发射,或产生重复记录),使用时需评估。
  • 时间戳策略:withProcessingTime() 是默认策略,withCreateTime() 面向 Kafka 消息自带 CreateTime 的 topic,withLogAppendTime() 则基于 broker 写入时间。

消息队列:KinesisIO

KinesisIO 提供对 AWS Kinesis 流的无界读取与写入,实现位于 KinesisIO.java。源码注释给出了三种典型读取姿势:

// 使用 AWS 默认凭据提供链(推荐)
p.apply(KinesisIO.read()
    .withStreamName("streamName")
    .withInitialPositionInStream(InitialPositionInStream.LATEST)
    .withAWSClientsProvider(DefaultAWSCredentialsProviderChain.getInstance(), STREAM_REGION)
 .apply( ... ));

// 使用明文 AWS 密钥
p.apply(KinesisIO.read()
    .withStreamName("streamName")
    .withInitialPositionInStream(InitialPositionInStream.LATEST)
    .withAWSClientsProvider("AWS_KEY", "AWS_SECRET", STREAM_REGION)
 .apply( ... ));

配置 KinesisIO 需要提供三样东西:

  1. 流名称(withStreamName);
  2. 流内起始读取位置:InitialPositionInStream.LATEST(从流末尾开始读取)或 InitialPositionInStream.TRIM_HORIZON(从流的最早位置开始),也可通过 withInitialTimestampInStream(Instant) 从任意时间点开始;
  3. AWS 客户端初始化数据:用于构造 AmazonKinesis 与 AmazonCloudWatch 客户端的凭据和区域。

如果使用 STS 等更复杂的授权方式,可以自行实现 AWSClientsProvider 接口并传入:

public class MyCustomKinesisClientProvider implements AWSClientsProvider {
  public AmazonKinesis getKinesisClient() {
    // 自行构造客户端
  }
  public AmazonCloudWatch getCloudWatchClient() {
    // 自行构造客户端
  }
}

p.apply(KinesisIO.read()
   .withStreamName("streamName")
   .withInitialPositionInStream(InitialPositionInStream.LATEST)
   .withAWSClientsProvider(new MyCustomKinesisClientProvider())
 .apply( ... ));

除基础配置外,KinesisIO 还提供 withMaxNumRecords(long)、withMaxReadTime(Duration)、withUpToDateThreshold(Duration)、withRequestRecordsLimit(int)、withArrivalTimeWatermarkPolicy() 等精细化控制项,并支持 readData() 直接产出 byte[] 数据(见 KinesisIO.java 中的 readData 方法)。

消息队列:PubsubIO

PubsubIO 是 Beam 对接 Google Cloud Pub/Sub 的官方连接器,实现位于 PubsubIO.java。它提供了丰富的读取入口:

  • readMessages():仅读取消息 payload;
  • readMessagesWithMessageId():payload + 消息 ID;
  • readMessagesWithAttributes():payload + 属性;
  • readMessagesWithAttributesAndMessageId():payload + 属性 + 消息 ID;
  • readMessagesWithAttributesAndMessageIdAndOrderingKey():进一步携带 ordering key;
  • readStrings():直接读取 UTF-8 编码字符串;
  • readProtos(Class<T>) / readProtoDynamicMessages(...) / readAvroGenericRecords(...):读取 protobuf 与 Avro 格式消息。

消息消费通过 fromTopic(...)(自动创建临时订阅)或 fromSubscription(...)(使用既有订阅)指定来源;withIdAttribute(...) 可利用消息属性做去重,withTimestampAttribute(...) 可指定用作事件时间的属性,withDeadLetterTopic(...) 则把无法处理的坏消息投递到死信 topic。

仓库中的移动游戏示例 LeaderBoard.java 演示了 PubsubIO 在真实管道中的组合用法——从 Pub/Sub 读取带自定义时间戳的字符串事件流:

PCollection<GameActionInfo> gameEvents =
    pipeline
        .apply(
            PubsubIO.readStrings()
                .withTimestampAttribute(GameConstants.TIMESTAMP_ATTRIBUTE)
                .fromTopic(options.getTopic()))
        .apply("ParseGameEvent", ParDo.of(new ParseEventFn()));

完整的游戏管道可参考仓库文档 mobile-gaming-example.md。

Python 生态下的流式输入连接器对比

Beam 拥有官方 Python SDK,目前支持 Java SDK 流式能力的一个子集,两个 SDK 之间的能力差距正在积极弥合。按照仓库文档 python-streaming.md 的说明,Python 流式管道执行自 Beam SDK 2.5.0 起可用(当时部分功能仍处于 beta / 受限状态),当前支持 Direct Runner 与 Dataflow Runner。

Spark 侧对应的是 PySpark。如前所述,Scala 代码编译为 JVM 字节码;PySpark 通过 Py4J 库让 Python 程序与 JVM 交互,从而访问 Java 类库、操作 Java 对象并注册 Java 回调,进而访问 RDD 等原生 Spark 对象。

下表汇总了 Beam 与 Spark DStreams 在 Python 下的主要流式输入连接器:

类别 子类 Apache Beam Apache Spark DStreams
文件系统 本地 io.textio textFileStream
文件系统 HDFS io.hadoopfilesystem hadoopConfiguration(通过 Py4J 的 sc._jsc 访问)+ textFileStream
对象存储 Google Cloud Storage io.gcp.gcsio textFileStream
对象存储 S3 N/A 同上
消息队列 Kafka N/A KafkaUtils
消息队列 Kinesis N/A KinesisUtils
消息队列 Cloud Pub/Sub io.gcp.pubsub N/A
其他 自定义接收器 BoundedSource 与 RangeTracker N/A

说明:这张表反映的是原始博客写作时间点(2018 年)的生态现状,其中 Python 侧 Kafka / Kinesis / S3 标记为 N/A。仓库中的 SDK 一直在演进,例如 Python 的 textio.py 如今已提供 ReadAllFromTextContinuously 等持续读取能力,选型时请以当前版本的实际支持情况为准。

文件与对象存储:textio / hadoopfilesystem / gcsio

Python 侧读取文本文件的入口是 apache_beam.io.textio.ReadFromText,其实现与参数定义位于 textio.py。该变换按换行符(\n、\r\n 或自定义 delimiter)解析文本为元素,默认 UTF-8 编码,主要参数包括:

  • file_pattern:本地路径或 GCS gs:// 路径,支持 *、? 和 [...] 通配符;
  • min_bundle_size:源被切分成 bundle 时的最小 bundle 大小;
  • compression_type:压缩文件处理方式,常用 CompressionTypes.AUTO 按扩展名自动识别;
  • strip_trailing_newlines:是否在解码前移除行尾换行符;
  • validate:是否在管道创建阶段校验文件存在;
  • skip_header_lines:每个文件跳过的表头行数;
  • delimiter / escapechar:自定义记录分隔符与转义字节。

HDFS 与 GCS 分别由 hadoopfilesystem.py 与 gcsio.py 提供底层文件系统支持。

消息队列:Python ReadFromPubSub

Python 侧读取 Pub/Sub 的入口是 apache_beam.io.gcp.pubsub.ReadFromPubSub,其源码位于 pubsub.py,构造函数参数如下:

ReadFromPubSub(
    topic=None,          # "projects/<project>/topics/<topic>" 形式;提供时 subscription 必须为 None
    subscription=None,   # "projects/<project>/subscriptions/<subscription>" 形式;
                         # 未指定时将从 topic 自动创建临时订阅;提供时 topic 必须为 None
    id_label=None,       # 用作消息唯一标识的属性;指定后可基于该属性去重;
                         # 未指定时无法保证流上不产生重复数据(去重仅尽力而为)
    with_attributes=False,  # True 时输出 PubsubMessage 对象,False 时输出 bytes(仅消息数据)
    timestamp_attribute=None  # 用作元素时间戳的属性;为 None 时使用消息发布时间
)

其中 timestamp_attribute 的取值支持两种格式:Unix 纪元以来的毫秒数值,或 UTC 时区的 RFC 3339 字符串(如 2015-10-29T23:41:41.123Z,亚秒部分可选)。早期版本中的 ReadStringsFromPubSub 已在 2.7.0 起被标记为 deprecated,建议统一使用 ReadFromPubSub 并自行解码。

从 python-streaming.md 还可以看到,把既有批处理管道改造成流处理时,至少需要:使用支持无界源(unbounded source)的 I/O 连接器,以及使用支持无界写入的连接器——Beam 会为读取持续更新数据源的管道创建无界 PCollection,Runner 必须以持续运行的流式作业处理它。

其他语言生态的流式输入支持

Scala

由于 Scala 与 Java 原生互操作,你可以在 Scala 程序中直接使用上面介绍的 Java 连接器。此外,Spotify 开源了 Apache Beam 的 Scala API(Scio),为 Scala 用户提供了更符合语言习惯的封装。

Go

仓库中已有 Apache Beam 的 Go SDK 且处于积极开发中。按原博客描述,它当时仍属实验性质,不建议直接用于生产环境;Spark 没有官方的 Go SDK。需要说明的是,仓库现状与此描述可能存在时间差,使用前请以 sdks/go 目录下的文档与代码为准。

R

Apache Beam 没有官方 R SDK。Spark Structured Streaming 有对应的 R SDK,但其流式输入目前仅支持文件源。

下一步:从对比走向实践

了解连接器清单只是第一步,真正用好流式输入还需要关注以下仓库资源:

流式输入的选型,本质上是“数据源形态(文件、对象存储、消息队列)× 语言 SDK × 目标 Runner”三者之间的匹配问题。对照本文的对比表逐项核验 Beam 与 Spark 的能力边界,再结合仓库源码确认各连接器的配置细节,就能为你的流式管道找到最稳妥的输入方案。

登录后查看全文
beam