Apache Pulsar Connector 开发实战指南:从 Source/Sink 接口到 NAR 打包与监控
Apache Pulsar Connector 开发实战指南:从 Source/Sink 接口到 NAR 打包与监控
Apache Pulsar IO 框架提供了一套统一的 Connector 机制,让开发者可以轻松地把数据从外部系统导入 Pulsar(Source),或从 Pulsar 导出到外部系统(Sink)。本篇指南以官方《How to develop Pulsar connectors》文档为骨架,结合当前仓库(2.10.x 主线)的源码实现,完整讲解 Connector 的两大接口、Schema 处理、测试、打包与监控,读完即可上手编写自己的 Pulsar Connector。
Connector 的本质:建立在 Pulsar Functions 之上的 IO 抽象
Pulsar Connector 本质上是一种特殊的 Pulsar Function,因此开发 Connector 的过程与开发 Pulsar Function 非常相似:你只需实现一个 Java 接口,Pulsar IO 运行时(运行在 Functions Worker 之上)会负责消息的拉取、投递、ack/fail 与生命周期管理。
Pulsar Connector 分为两种类型:
| 类型 | 描述 | 典型示例 |
|---|---|---|
| Source | 将数据从另一个系统导入 Pulsar | RabbitMQ Source Connector 将 RabbitMQ 队列中的消息导入 Pulsar topic |
| Sink | 将数据从 Pulsar 导出到另一个系统 | Kinesis Sink Connector 将 Pulsar topic 中的消息导出到 Kinesis stream |
两个核心接口都定义在 pulsar-io/core 模块的 org.apache.pulsar.io.core 包下:
- Source.java:
public interface Source<T> extends AutoCloseable - Sink.java:
public interface Sink<T> extends AutoCloseable
两者都标注了 @InterfaceAudience.Public 与 @InterfaceStability.Stable,说明它们是稳定的公共扩展点,可以放心实现。
开发 Source Connector
开发一个 Source Connector 就是实现 Source<T> 接口,核心是以下两个方法。
1. 实现 open 方法:完成初始化
/**
* Open connector with configuration
*
* @param config initialization config
* @param sourceContext
* @throws Exception IO type exceptions when opening a connector
*/
void open(final Map<String, Object> config, SourceContext sourceContext) throws Exception;
这个方法在 Source Connector 被初始化时调用(实现见 Source.java):
- 你可以通过传入的
config参数读取所有 Connector 专属配置(通常是 YAML 配置文件中的键值对),并初始化所需的资源。例如 Kafka Connector 就在这个open方法里创建 Kafka 客户端。 - 同时,Pulsar 运行时提供一个 SourceContext,让 Connector 访问运行时资源(如
getSourceName()、getOutputTopic()、newOutputMessage()、newConsumerBuilder()),以及收集 metrics、记录日志、操作状态等。实现类应保存这个SourceContext以备后续使用。
2. 实现 read 方法:读取下一条消息
/**
* Reads the next message from source.
* If source does not have any new messages, this call should block.
* @return next message from source. The return result should never be null
* @throws Exception
*/
Record<T> read() throws Exception;
注意两点(见 Source.java):
- 当源系统没有新消息时,实现必须阻塞等待而不是返回
null。 - 返回值是
Record<T>,它封装了 Pulsar IO 运行时所需的全部信息。
Record 接口:Source 与运行时的信息载体
Record.java 是 org.apache.pulsar.functions.api 包中的公共接口,其中绝大多数方法都有默认实现(返回 Optional.empty() 或空集合),因此实现一个 Record 只需重点关注 getValue() 与 ack()/fail()。
Record 提供以下变量(通过 getter 暴露):
| 变量 | 是否必需 | 描述 |
|---|---|---|
TopicName |
否 | 该 Record 来源的 Pulsar topic 名 |
Key |
否 | 消息可选的 key 标签;路由模式参见 concepts-messaging |
Value |
是 | Record 的实际数据 |
EventTime |
否 | 来自源系统的事件时间 |
PartitionId |
否 | 若来自分区源则返回分区 ID;与 RecordSequence 一起作为唯一标识的一部分,供 Pulsar IO 运行时做消息去重,实现精确一次(exactly-once)处理 |
RecordSequence |
否 | 若来自有序源则返回序号;同样参与唯一标识与去重 |
Properties |
否 | 用户自定义属性 |
DestinationTopic |
否 | 消息应写入的目标 topic |
Message |
否 | 携带用户发送数据的类,见 Message.java |
Record 还提供以下方法:
| 方法 | 描述 |
|---|---|
ack |
确认该 Record 已完全处理(Record.java) |
fail |
表示该 Record 处理失败(Record.java) |
源码实例:Kafka Source 的 Record 实现
仓库中的 KafkaAbstractSource.java 是官方文档推荐的参考实现(见文档 "For more information about how to create a source connector" 的 tip)。它的内部类 KafkaRecord 展示了如何把 Kafka ConsumerRecord 映射到 Pulsar Record:
getPartitionId()返回Integer.toString(record.partition())(L202-L204)getRecordSequence()返回 Kafka 的record.offset()(L212-L214)ack()通过completableFuture.complete(null)通知内部消费线程完成确认(L227-L229)
这正是 PartitionId + RecordSequence 参与去重、以及 ack/fail 回调驱动提交语义的具体体现。
处理 Source 的 Schema 信息
Pulsar IO 会自动处理 Schema,并提供基于 Java 泛型的强类型 API。
场景一:已知 Schema 类型
如果你明确知道要产出的 Schema 类型,可以在 Source 声明中直接指定对应的 Java 类:
public class MySource implements Source<String> {
public Record<String> read() {}
}
场景二:兼容任意 Schema(byte[] + Schema.AUTO_PRODUCE_BYTES)
如果你希望 Source 能与任意 Schema 协同工作,可以使用 byte[](或 ByteBuffer)并配合 Schema.AUTO_PRODUCE_BYTES():
public class MySource implements Source<byte[]> {
public Record<byte[]> read() {
Schema wantedSchema = ....
Record<byte[]> myRecord = new MyRecordImplementation();
....
}
class MyRecordImplementation implements Record<byte[]> {
public byte[] getValue() {
return ....encoded byte[]...that represents the value
}
public Schema<byte[]> getSchema() {
return Schema.AUTO_PRODUCE_BYTES(wantedSchema);
}
}
}
场景三:正确处理 KeyValue 类型
要正确处理 KeyValue 类型,Record 实现需要遵循以下准则:
- 必须实现 KVRecord.java 接口,并实现
getKeySchema()、getValueSchema()和getKeyValueEncodingType()三个方法(其KeyValueEncodingType取值来自org.apache.pulsar.common.schema.KeyValueEncodingType,即SEPARATED或INLINE); Record.getValue()必须返回KeyValue对象;Record.getSchema()可以返回null。
当 Pulsar IO 运行时遇到 KVRecord 时,会自动完成以下转换:
- 正确设置
KeyValueSchema; - 根据
KeyValueEncoding(SEPARATED 或 INLINE)编码消息 Key 与消息 Value。
仓库中 KafkaAbstractSource.java 的 KeyValueKafkaRecord 就是标准范例:它实现了 KVRecord,提供独立的 key/value schema,并固定返回 KeyValueEncodingType.SEPARATED。
开发 Sink Connector
开发 Sink Connector 与 Source 类似,需要实现 Sink.java 接口,即实现 open 与 write 两个方法。
1. 实现 open 方法
/**
* Open connector with configuration
*
* @param config initialization config
* @param sinkContext
* @throws Exception IO type exceptions when opening a connector
*/
void open(final Map<String, Object> config, SinkContext sinkContext) throws Exception;
同样在初始化时调用(见 Sink.java)。运行时传入的 SinkContext 提供了 getSinkName()、getInputTopics()、getSubscriptionType() 以及 seek()/pause()/resume() 等订阅控制能力。
2. 实现 write 方法
/**
* Write a message to Sink
* @param record record to write to sink
* @throws Exception
*/
void write(Record<T> record) throws Exception;
在 write 实现中,你可以:
- 自行决定如何把
Value和Key写入实际的外部系统; - 利用
PartitionId、RecordSequence等提供的信息实现不同的处理保证(如幂等写入、顺序写入); - 必须在消息成功发送后调用
record.ack()、发送失败时调用record.fail(),将处理结果反馈给 Pulsar IO 运行时。
处理 Sink 的 Schema 信息
与 Source 相同,Pulsar IO 会自动处理 Schema 并提供强类型 API。
已知 Schema 类型
public class MySink implements Sink<String> {
public void write(Record<String> record) {}
}
兼容任意 Schema:使用 GenericObject
如果要实现一个适配任意 Schema 的 Sink,可以使用特殊的 GenericObject 接口:
public class MySink implements Sink<GenericObject> {
public void write(Record<GenericObject> record) {
Schema schema = record.getSchema();
GenericObject genericObject = record.getValue();
if (genericObject != null) {
SchemaType type = genericObject.getSchemaType();
Object nativeObject = genericObject.getNativeObject();
...
}
....
}
}
GenericObject.java 定义在 org.apache.pulsar.client.api.schema 包中,提供两个方法:
getSchemaType():返回消息的 SchemaType(如BYTES、STRING、AVRO、JSON、PROTOBUF_NATIVE);getNativeObject():返回对象的原生表示,例如 AVRO 的GenericRecord、String或byte[]。
AVRO / JSON / Protobuf 记录
对于 AVRO、JSON、PROTOBUF_NATIVE 类型的记录,可以把 genericObject 强转为 GenericRecord.java,使用 getFields() 与 getField() API 读取字段,并通过 genericObject.getNativeObject() 访问原生 AVRO 记录。
KeyValue 类型
对于 KeyValue 类型,可以同时拿到 key 与 value 各自的 Schema:
public class MySink implements Sink<GenericObject> {
public void write(Record<GenericObject> record) {
Schema schema = record.getSchema();
GenericObject genericObject = record.getValue();
SchemaType type = genericObject.getSchemaType();
Object nativeObject = genericObject.getNativeObject();
if (type == SchemaType.KEY_VALUE) {
KeyValue keyValue = (KeyValue) nativeObject;
Object key = keyValue.getKey();
Object value = keyValue.getValue();
KeyValueSchema keyValueSchema = (KeyValueSchema) schema;
Schema keySchema = keyValueSchema.getKeySchema();
Schema valueSchema = keyValueSchema.getValueSchema();
}
....
}
}
仓库中 tests/integration/src/test/java/org/apache/pulsar/tests/integration/io/PulsarGenericObjectSinkTest.java 即为针对 GenericObject Sink 的端到端验证示例,可作为编写此类 Sink 时的对照参考。
测试 Connector
Connector 测试的难点在于:Pulsar IO Connector 需要同时与两个系统交互——Pulsar 本身,以及 Connector 所连接的外部系统,二者往往难以 mock。官方推荐的策略是:在 mock 外部服务的前提下编写专项测试。
单元测试
为 Connector 编写针对纯逻辑(如配置解析、Record 构建、Schema 转换)的单元测试。
集成测试
在单元测试覆盖充分后,补充独立的集成测试来验证端到端功能。Pulsar 仓库所有 Connector 集成测试均基于 Testcontainers,其中包含 PulsarIOTestBase、PulsarIOTestRunner 以及针对 RabbitMQ、Kinesis 等各类 Connector 的 Tester 类。
打包 Connector
开发和测试完成后,需要把 Connector 打包,以便提交到 Pulsar Functions 集群运行。有两种方式:NAR 与 uber JAR。
注意:如果你计划将 Connector 打包分发供他人使用,有义务为自己的代码做恰当的 license 与 copyright 声明,并确保所有依赖库及发行物都包含 license 与 copyright。若使用 NAR 方式,NAR 插件会自动在生成的 NAR 包内创建
DEPENDENCIES文件,包含 Connector 所有库的 license 与 copyright 信息,帮你自动完成这项义务。
方式一:NAR(推荐,与内置 Connector 一致)
NAR(NiFi Archive)是 Apache NiFi 使用的一种自定义打包机制,用于提供一定程度的 Java ClassLoader 隔离。Pulsar 使用同一机制打包所有内置 Connector(见 pulsar-io 目录下各模块)。
打包 NAR 最简单的方式是使用 nifi-nar-maven-plugin,在 Connector 的 Maven 项目中加入:
<plugins>
<plugin>
<groupId>org.apache.nifi</groupId>
<artifactId>nifi-nar-maven-plugin</artifactId>
<version>1.2.0</version>
</plugin>
</plugins>
同时,必须在 resources/META-INF/services/pulsar-io.yaml 中创建如下内容的描述文件:
name: connector name
description: connector description
sourceClass: fully qualified class name (only if source connector)
sinkClass: fully qualified class name (only if sink connector)
仓库中每个内置 Connector 都带有该文件,例如 pulsar-io/aerospike/src/main/resources/META-INF/services/pulsar-io.yaml 的完整内容为:
name: aerospike
description: Aerospike database sink
sinkClass: org.apache.pulsar.io.aerospike.AerospikeStringSink
sinkConfigClass: org.apache.pulsar.io.aerospike.AerospikeSinkConfig
而 pulsar-io/twitter/pom.xml 则展示了在 <build><plugins> 中引用 nifi-nar-maven-plugin(由父 POM 统一管理版本)的完整写法,是使用 NAR 打包 Connector 的最佳参考。
Gradle 用户可以使用 Gradle Plugin Portal 上提供的 Gradle Nar 插件。
方式二:Uber JAR
另一种方案是制作包含 Connector 所有 JAR 与资源文件的 uber JAR,这种方式不需要特定的内部目录结构。使用 maven-shade-plugin 即可:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.1.1</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<filters>
<filter>
<artifact>*:*</artifact>
</filter>
</filters>
</configuration>
</execution>
</executions>
</plugin>
监控 Connector
Connector 在 Pulsar 内外搬运数据,因此随时确保运行中的 Connector 健康非常重要。可以通过以下两种方式监控已部署的 Java Connector:
- 查看 Pulsar 提供的 metrics:Java Connector 会暴露可采集的 metrics,用于监控其健康状况,具体采集方法参见 monitoring 指南。
- 设置并查看自定义 metrics:除 Pulsar 内置 metrics 外,Java Connector 还可以自定义 metrics。Functions Worker 会自动把用户定义的 metrics 采集到 Prometheus,并可在 Grafana 中查看。
自定义 metrics 的底层支持来自 BaseContext.java 中的 void recordMetric(String metricName, double value) 方法,SourceContext 与 SinkContext 都继承自 BaseContext,因此在 open/write 中可以随时调用。
下面是一个为 Java Connector 自定义 metrics 的完整示例:
public class TestMetricSink implements Sink<String> {
@Override
public void open(Map<String, Object> config, SinkContext sinkContext) throws Exception {
sinkContext.recordMetric("foo", 1);
}
@Override
public void write(Record<String> record) throws Exception {
}
@Override
public void close() throws Exception {
}
}
小结
开发一个 Pulsar Connector 的完整流程可归纳为四步:实现接口(Source 的 open/read,或 Sink 的 open/write)、正确处理 Schema(强类型泛型、byte<a href="https://link.gitcode.com/i/c02c17091b96c58a0343687f12c5b619" target="_blank">]+AUTO_PRODUCE_BYTES、KVRecord、GenericObject)、测试与打包(Testcontainers 集成测试 + NAR / uber JAR)、上线监控(Pulsar 内置 metrics + recordMetric 自定义 metrics)。官方文档中提到的所有接口与机制均可在当前仓库的 [pulsar-io/core 与 pulsar-functions/api-java 中找到对应实现,内置的 Kafka Source、Aerospike Sink 与 Twitter Connector 则是可直接对照学习的完整范例。