Apache Pulsar Connector 开发实战指南:从 Source/Sink 接口到 NAR 打包与监控

原创2026-09-24 10:25:551,895 阅读
文章标签:消息队列后端流处理

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:

  1. 查看 Pulsar 提供的 metrics:Java Connector 会暴露可采集的 metrics,用于监控其健康状况,具体采集方法参见 monitoring 指南。
  2. 设置并查看自定义 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 则是可直接对照学习的完整范例。

登录后查看全文
pulsar