SeaTunnel Apache Pulsar 连接器完全指南:从版本演进到 Source/Sink 实战与源码解析
SeaTunnel Apache Pulsar 连接器完全指南:从版本演进到 Source/Sink 实战与源码解析
本文以 SeaTunnel 仓库中 Apache Pulsar 连接器变更日志 为核心骨架,完整梳理 Pulsar Source / Sink 从 2.2.0-beta 到 2.3.12 的演进脉络,并在此基础上结合官方源连接器文档、Sink 连接器文档 与
seatunnel-connectors-v2/connector-pulsar模块源码,系统讲解连接器架构、全部配置参数、多表读写、游标(Cursor)位点控制与精确一次写入的实现原理。读完本文,你将能够基于当前仓库版本完整掌握 Pulsar 连接器的能力边界、正确配置批式/流式/多表读写任务,并理解其底层源码实现。
一、Pulsar 连接器演进全景:一份变更日志背后的技术主线
Apache SeaTunnel 的每个连接器在 docs/zh/connectors/changelog/ 目录下都维护着一份独立的变更日志。打开 connector-pulsar.md,可以看到 Pulsar 连接器从 2.2.0-beta 到 2.3.12 的完整提交历史。将这些条目按功能主线重组,能清晰看到连接器从"可用"到"健壮、多表、高性能"的演进路径:
1.1 能力从无到有:Sink 与多格式读取的落地
- 2.3.4 版本是 Pulsar 连接器能力的重要分水岭:[Feature][Connector-v2][PulsarSink]Add Pulsar Sink Connector 提交(Commit
543d2c5086)正式引入 Pulsar Sink 连接器,使 SeaTunnel 具备向 Pulsar 写入数据的能力,此前连接器只有 Source 方向。 - 同版本的 [Feature][Json-format] support read format for pulsar(Commit
7d61ae93e7)虽然是 2.3.2 的条目,但意味着 JSON 格式读取能力正式打通,为后续 canal_json、avro、text 等格式矩阵奠定了格式层基础。 - 2.3.6 版本:[Feature][Kafka] Support multi-table source read(Commit
60104602d1)将多表 Source 读取能力引入消息类连接器,Pulsar 随之获得多表读取支持。
1.2 性能与稳定性持续加固
- 2.3.4 版本:[PulsarSource]Improve pulsar throughput performance(Commit
37461f4f3e)专项优化吞吐性能。 - 2.3.1 版本密集修复了一批真实问题:PulsarSource consumer ack 异常(Commit
9725d675da)、topic-pattern选项 bug(Commitaee2c580ea)、[Improve][Connector-v2][Pulsar] 设置 Pulsar 消费线程名称(Commite567203f7d),以及统一 Pulsar Source 的异常体系(Commit4fe9323419)。 - 2.3.2 版本修复"无法持续消费消息"的 bug(Commit
a6705cc5bf)。 - 2.2.0-beta 版本修复 restore 时无法标记
#noMoreNewSplits的问题(Commit5ad69076b3),并把 Handover 组件下沉到 common 模块复用(Commitd94a874bcb)。
1.3 配置模型走向规范化
- 2.3.0 版本:[Feature][Connector][pulsar] expose configurable options in Pulsar(Commit
200faa7c29)将大量 Pulsar 底层选项暴露为可配置项;随后修复 conditional options(Commit0066affacf)与 OptionRule 全连接器一致性(Commit226dc6a119)。 - 2.2.0-beta 版本:[Improve][Connector-V2] Pulsar support user-defined schema(Commit
16cabe6a35)与 pulsar source options 文档(Commit59ce8a2b32)。 - 2.3.10 ~ 2.3.12 版本走向 API 与基础设施优化:restruct connector common options(Commit
f3499a6eeb)、[Improve][API] Optimize the enumerator API semantics and reduce lock calls at the connector level(Commit9212a77140,2.3.12)、[improve] pulsar options(Commit26a2160c80,2.3.12)。 - 2.3.11 版本:Feature][Checkpoint] 为 source/sink state 类补充 serialVersionUID 缺失检查脚本(Commit
4f5adeb1c7),保证状态类序列化兼容性——这正是 [PulsarSplitEnumeratorState 等 checkpoint 状态类的质量保障措施。
阅读建议:变更日志中每个条目都附有原始提交 ID,需要追查某个具体修复的完整 diff 时,可直接在仓库 git 历史中按该 ID 检索。
二、连接器能力总览:引擎支持与特性矩阵
根据 Pulsar 源连接器文档 与 Pulsar Sink 连接器文档,连接器在 Spark、Flink、SeaTunnel Zeta 三种引擎下均可运行。
Source 侧关键特性:
| 特性 | 支持状态 |
|---|---|
| 批读取(Batch) | ✅ |
| 流读取(Streaming) | ✅ |
| 精确一次(Exactly-Once) | ✅ |
| 列投影(Column Projection) | ❌ |
| 并行读取(Parallelism) | ✅ |
| 用户自定义 Split | ❌ |
| 多表读取(Multi-Table) | ✅ |
Sink 侧关键特性:
| 特性 | 支持状态 |
|---|---|
| 精确一次(Exactly-Once) | ✅ |
| 多表写入(Multi-Table) | ✅ |
| 定时刷新 | ❌ |
其中"多表读取/写入"正是 2.3.6 与 2.3.4 两次功能提交的直接产物,也是本连接器区别于传统单 topic 连接器的核心能力。
三、Pulsar Source 实战:参数全解与配置示例
3.1 Source 参数总表
以下参数表完整继承自官方文档,并结合 PulsarSourceOptions.java 源码中的默认值与校验逻辑逐项展开:
| 名称 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
| topic | String | 否 | - | 单表读取的 topic 名称,支持逗号分隔多个。只能与 topic-pattern、tables_configs 三选一 |
| topic-pattern | String | 否 | - | 匹配 topic 名称的正则表达式。与 topic、tables_configs 三选一 |
| table_path | String | 否 | - | 多表模式中单个配置项对应的逻辑表标识 |
| tables_configs | Array | 否 | - | 多表读取配置,每个 item 可覆盖全局默认值。与 topic、topic-pattern 三选一 |
| topic-discovery.interval | Long | 否 | -1 | 发现新 topic 分区的间隔(毫秒),非正值禁用。仅 topic-pattern 模式下生效 |
| subscription.name | String | 单表必填 / 多表必配 | - | 消费者订阅名 |
| client.service-url | String | 是 | - | 客户端服务 URL,如 pulsar://localhost:6650 |
| admin.service-url | String | 是 | - | 管理端 HTTP URL,如 http://localhost:8080 |
| auth.plugin-class | String | 否 | - | 认证插件类名 |
| auth.params | String | 否 | - | 认证插件参数 |
| poll.timeout | Integer | 否 | 100 | 单次拉取最长等待时间(毫秒) |
| poll.interval | Long | 否 | 50 | 两次拉取间隔(毫秒) |
| poll.batch.size | Integer | 否 | 500 | 单次拉取最大消息数 |
| cursor.startup.mode | Enum | 否 | LATEST | 启动位点:EARLIEST / LATEST / SUBSCRIPTION / TIMESTAMP |
| cursor.startup.timestamp | Long | 否 | - | TIMESTAMP 模式下的起始时间戳(毫秒) |
| cursor.reset.mode | Enum | SUBSCRIPTION 时必填 | - | 订阅位点重置策略:EARLIEST / LATEST |
| cursor.stop.mode | Enum | 否 | NEVER | 停止位点:NEVER(流式)/ LATEST(批式)/ TIMESTAMP(批式) |
| cursor.stop.timestamp | Long | 否 | - | TIMESTAMP 模式下的停止时间戳(毫秒) |
| schema | Config | 否 | - | 字段名与字段类型定义 |
| format | String | 否 | json | json / canal_json / avro / text(text 仅单表) |
| field_delimiter | String | 否 | , | text 格式字段分隔符 |
| common-options | - | 否 | - | Source 通用参数,见 Source Common Options |
源码中的默认值与校验依据:以上默认值(topic-discovery.interval=-1、poll.timeout=100、poll.interval=50、poll.batch.size=500、cursor.startup.mode=LATEST、cursor.stop.mode=NEVER、format=json、field_delimiter=,)均直接定义在 PulsarSourceOptions.java 与 PulsarBaseOptions.java 中,可通过 Options.key(...).defaultValue(...) 声明直观核对。
3.2 三种 topic 指定方式的互斥约束
从 PulsarSourceFactory.optionRule() 可以看到,topic、topic-pattern、tables_configs 被声明为 exclusive(互斥)关系;同时 subscription.name 与 client.service-url、admin.service-url 都是非空校验的必填项。配置校验失败会抛出 CONFIG_VALIDATION_FAILED 错误,例如:
- 单表模式必须配置
subscription.name(见PulsarSourceFactory.validateSourceOptions); cursor.startup.mode=TIMESTAMP时必须同时配置cursor.startup.timestamp;cursor.startup.mode=SUBSCRIPTION时必须配置cursor.reset.mode;cursor.stop.mode=TIMESTAMP时必须配置cursor.stop.timestamp。
这些条件校验逻辑统一由 PulsarMultiTableConfig.validateTableConfig 在 PulsarMultiTableConfig.java 中执行,并有 PulsarMultiTableConfigTest 单元测试逐项覆盖。
3.3 典型配置示例
示例一:单 Topic 批式读取(cursor.stop.mode = LATEST 界定批边界):
env {
parallelism = 1
job.mode = "BATCH"
}
source {
Pulsar {
topic = "topic-it"
subscription.name = "seatunnel"
client.service-url = "pulsar://localhost:6650"
admin.service-url = "http://localhost:8080"
cursor.startup.mode = "EARLIEST"
cursor.stop.mode = "LATEST"
format = json
schema = {
fields {
c_string = string
c_boolean = boolean
c_int = int
c_bigint = bigint
c_double = double
c_timestamp = timestamp
}
}
}
}
示例二:流式持续读取(cursor.stop.mode = NEVER 表示无界,配合 checkpoint 实现容错):
env {
parallelism = 2
job.mode = "STREAMING"
checkpoint.interval = 10000
}
source {
Pulsar {
topic = "persistent://public/default/events"
subscription.name = "seatunnel-stream"
client.service-url = "pulsar://localhost:6650"
admin.service-url = "http://localhost:8080"
cursor.startup.mode = "LATEST"
cursor.stop.mode = "NEVER"
format = json
schema = {
fields {
event_id = string
user_id = bigint
payload = string
}
}
}
}
示例三:text 格式(单表模式,用 field_delimiter 拆分字段):
source {
Pulsar {
topic = "text-events"
subscription.name = "seatunnel-text-sub"
client.service-url = "pulsar://localhost:6650"
admin.service-url = "http://localhost:8080"
cursor.startup.mode = "EARLIEST"
cursor.stop.mode = "LATEST"
format = text
field_delimiter = "|"
schema = {
fields {
id = int
name = string
}
}
}
}
示例四:canal_json 格式(对接 Canal 变更事件数据流):
source {
Pulsar {
topic = "test-cdc_mds"
subscription.name = "seatunnel-cdc-sub"
client.service-url = "pulsar://localhost:6650"
admin.service-url = "http://localhost:8080"
cursor.startup.mode = "EARLIEST"
cursor.stop.mode = "LATEST"
format = canal_json
schema = {
fields {
id = int
name = string
description = string
weight = string
}
}
}
}
示例五:avro 格式(必须配置 schema,见 PulsarMultiTableConfig.validateAvroSchema 的强制校验):
env {
parallelism = 1
job.mode = "BATCH"
}
source {
Pulsar {
topic = "test_avro_topic"
subscription.name = "seatunnel-avro"
client.service-url = "pulsar://localhost:6650"
admin.service-url = "http://localhost:8080"
cursor.startup.mode = "EARLIEST"
cursor.stop.mode = "LATEST"
format = avro
schema = {
fields {
id = bigint
c_string = string
c_int = int
c_double = double
c_timestamp = timestamp
}
}
}
}
3.4 多表读取:tables_configs 详解
多表读取是 2.3.6 版本引入的核心能力(对应 Feature][Kafka] Support multi-table source read 提交),每个 item 可覆盖全局默认的 format、cursor 相关参数和 subscription.name。关键约束(源码级依据均在 [PulsarMultiTableConfig.java 中):
- 每个 item 必须且只能配置
topic或topic-pattern之一,否则抛 "must specify exactly one of 'topic' or 'topic-pattern'"; - 使用
topic-pattern时table_path必填; subscription.name必须在全局或 item 内存在(item 内优先级更高,测试用例 验证了"无全局订阅名、仅 item 配置"的合法场景);- 多表模式仅支持
JSON、CANAL_JSON、AVRO,TEXT会被拒绝(见validateFormat与对应测试shouldRejectTextFormatInTablesConfigs); - 显式
topic与任何topic-pattern不允许重叠(validateTopicOverlap); - 多个
topic-pattern同时匹配同一 topic 时,按tables_configs声明顺序选择第一个,因此更具体的 pattern 应放在更通用 pattern 之前;这一确定性路由由 MultiTablePartitionDiscoverer 在运行时解析,测试shouldAllowOverlappingTopicPatternsForDeterministicRuntimeRouting验证了重叠 pattern 不会导致作业失败。 - batch 模式限制:多表配置必须全部有界;只要配置了多于一张表且任意一张表使用
cursor.stop.mode = NEVER,整个 Source 即视为无界,在 batch 作业中会直接报错(见 PulsarSource.setJobContext)。
多表读取配置示例:
source {
Pulsar {
client.service-url = "pulsar://localhost:6650"
admin.service-url = "http://localhost:8080"
cursor.startup.mode = "EARLIEST"
cursor.stop.mode = "LATEST"
format = "json"
tables_configs = [
{
table_path = "db.orders"
topic = "persistent://public/default/orders"
subscription.name = "sub-orders"
schema = {
fields {
order_id = int
amount = double
}
}
},
{
table_path = "db.users"
topic-pattern = "persistent://public/default/users-.*"
subscription.name = "sub-users"
schema = {
fields {
user_id = int
name = string
}
}
}
]
}
}
源码归一化模型:PulsarMultiTableConfig.of() 将"无 tables_configs 的单表配置"也转换为只含一个 item 的 tableConfigs 列表(见 parseSingleTable),使下游运行时(枚举器、Reader、反序列化)共用同一套多表代码路径——这正是 2.3.12 中"enumerator API 语义优化"等重构得以低成本落地的基础。
3.5 topic-pattern 动态发现
组合使用 topic-pattern 与 topic-discovery.interval 可以自动发现新增 topic:
source {
Pulsar {
topic-pattern = "persistent://public/default/orders-.*"
subscription.name = "seatunnel-orders"
client.service-url = "pulsar://localhost:6650"
admin.service-url = "http://localhost:8080"
topic-discovery.interval = 30000
cursor.startup.mode = "EARLIEST"
cursor.stop.mode = "LATEST"
format = json
schema = {
fields {
order_id = bigint
amount = double
}
}
}
}
注意两个边界约束(源码依据见 PulsarSource.validateBoundedDiscovery):
topic-discovery.interval仅在使用topic-pattern时生效;- 有界(BOUNDED)作业不支持动态分区发现:当作业有界且配置了正值的 discovery interval 时会抛 "Bounded streams do not support dynamic partition discovery.",即动态发现只适用于无界流式作业。
四、Pulsar Sink 实战:参数全解与配置示例
4.1 Sink 参数总表
参数定义位于 PulsarSinkOptions.java,完整参数如下:
| 名称 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
| topic | String | 否 | - | 目标 topic。单表必配;多表数据带表标识时可省略 |
| client.service-url | String | 是 | - | 客户端服务地址,如 pulsar://localhost:6650 |
| admin.service-url | String | 是 | - | 管理端 HTTP 地址,如 http://localhost:8080 |
| auth.plugin-class | String | 否 | - | 认证插件类名 |
| auth.params | String | 否 | - | 认证参数,与 auth.plugin-class 一起配置 |
| format | String | 否 | json | 数据格式:json / text / avro |
| field_delimiter | String | 否 | , | text 格式字段分隔符 |
| semantics | Enum | 否 | AT_LEAST_ONCE | NON / AT_LEAST_ONCE / EXACTLY_ONCE |
| transaction_timeout | Int | 否 | 600 | Pulsar 事务超时(秒),仅 EXACTLY_ONCE 生效 |
| pulsar.config | Map | 否 | - | 透传给 Pulsar producer 的额外参数 |
| message.routing.mode | Enum | 否 | RoundRobinPartition | SinglePartition / RoundRobinPartition |
| partition_key_fields | Array | 否 | - | 用于生成消息 key 的字段 |
| multi_table_sink_replica | Int | 否 | 1 | 多表写入时的写入器副本数 |
| common-options | Config | 否 | - | Sink 通用参数,见 Sink Common Options |
4.2 三种一致性语义的实现机制
semantics 枚举定义在 PulsarSemantics.java,三种语义在 PulsarSinkWriter 中分别落地:
NON:直接sendAsync()发送,不与 checkpoint 协调,不计数pendingMessages。作业重启、重试或网络异常后数据可能重复或丢失。AT_LEAST_ONCE(默认):每条消息sendAsync()后通过pendingMessages计数与sendMessageException记录异步发送结果;snapshotState时调用flushPendingMessages()等待全部发送完成再触发 checkpoint,实现"至少一次"。EXACTLY_ONCE:基于 Pulsar 事务两阶段提交(2PC)。流程如下:PulsarConfigUtil.createClient在构建 client 时调用enableTransaction(true)开启事务能力(PulsarConfigUtil.java);- Writer 启动即创建事务
this.transaction = createTransaction(),发送时把事务注入TypedMessageBuilder(createTypedMessageBuilder); prepareCommit()返回携带TxnID的PulsarCommitInfo,snapshotState记录 TxnID 并新建下一个事务;- 引擎侧由 PulsarSinkCommitter 通过
TransactionCoordinatorClient.commit(txnID)提交;失败路径调用abort()。
两个重要前置条件(源码注释与文档一致):
- Pulsar 集群必须开启事务能力;
transaction_timeout(默认 600 秒)必须大于 checkpoint 间隔,否则事务会在提交前被自动中止;- 事务模式下 producer 必须禁用 sendTimeout(
producerBuilder.sendTimeout(0, TimeUnit.SECONDS)),这是 Pulsar 官方对事务消息生产者硬性要求,见 PulsarConfigUtil.createProducer。
精确一次写入配置示例:
env {
parallelism = 1
job.mode = "STREAMING"
checkpoint.interval = 10000
}
sink {
Pulsar {
topic = "orders"
client.service-url = "pulsar://localhost:6650"
admin.service-url = "http://localhost:8080"
semantics = "EXACTLY_ONCE"
transaction_timeout = 600
format = json
}
}
4.3 多表写入与动态路由
Sink 实现了 SupportMultiTableSink 接口(PulsarSink.java)。核心路由逻辑在 PulsarSinkWriter.resolveTopic:
- 优先使用
SeaTunnelRow.getTableId()作为目标 topic(多表/整库同步场景); - 若行数据无表标识,则回退使用全局
topic; - 两者都没有时抛出
Topic must be configured when SeaTunnelRow.getTableId() is null。
每个 topic 对应独立的 Producer,缓存在 producerMap 中按需懒创建。配置示例:
sink {
Pulsar {
client.service-url = "pulsar://localhost:6650"
admin.service-url = "http://localhost:8080"
multi_table_sink_replica = 2
format = json
}
}
4.4 消息 Key、路由模式与 producer 透传参数
partition_key_fields:指定用哪些字段生成消息 key。实现见 PulsarSinkWriter.createKeySerializationSchema:所选字段必须存在于上游行类型中,否则抛 "Partition key field not found";生成的 key 为 JSON 形式,例如上游有 name、age 字段,配置 partition_key_fields = ["name"] 会生成 {"name":"Jack"}。
message.routing.mode(对应 Pulsar 客户端 MessageRoutingMode 枚举):
SinglePartition:无 key 时随机选一个分区写入全部消息;有 key 时按 key 哈希选分区。RoundRobinPartition(默认):无 key 时轮询写各分区;注意 Pulsar 的轮询发生在批处理延迟边界上,并非逐条轮询。
配置示例:
sink {
Pulsar {
topic = "orders"
client.service-url = "pulsar://localhost:6650"
admin.service-url = "http://localhost:8080"
partition_key_fields = ["order_id"]
message.routing.mode = "SinglePartition"
format = json
}
}
pulsar.config:通过 Map 形式透传 producer 属性(producerBuilder.properties(...),见 PulsarConfigUtil.createProducer),可用于调整超时、批大小、压缩等:
sink {
Pulsar {
topic = "topic_test"
client.service-url = "pulsar://localhost:6650"
admin.service-url = "http://localhost:8080"
format = json
pulsar.config = {
sendTimeoutMs = 30000
batchingMaxMessages = 1000
}
}
}
4.5 完整写入示例(FakeSource → Pulsar)
env {
parallelism = 1
job.mode = "BATCH"
}
source {
FakeSource {
plugin_output = "fake"
row.num = 10
schema = {
fields {
c_string = string
c_int = int
c_bigint = bigint
c_double = double
c_timestamp = timestamp
}
}
}
}
sink {
Pulsar {
topic = "topic_test"
client.service-url = "pulsar://localhost:6650"
admin.service-url = "http://localhost:8080"
format = json
pulsar.config = {
sendTimeoutMs = 30000
}
}
}
五、源码级原理:连接器运行时解剖
5.1 整体架构:Source 三组件协作模型
Pulsar Source 遵循 SeaTunnel 的 SeaTunnelSource 三组件模型,核心类关系如下:
PulsarSource(源码):入口类,实现SupportParallelism,负责构建三类配置(Admin/Client/Consumer)与反序列化 schema,并分发创建 Reader 与 Enumerator。getBoundedness()依据各表的StopCursor是否为NeverStopCursor动态判定有界/无界。PulsarSplitEnumerator(源码):通过PulsarDiscoverer发现 topic 分区,把每个TopicPartition包装为PulsarPartitionSplit推送给对应 reader。关键逻辑:- 分区均匀分配:
getSplitOwner用HashUtils.bucketIndex(topic.hashCode() * 31, numReaders)计算起点,再按分区号递增取模,保证同一 topic 的连续分区散落到不同 reader; - 动态发现:
open()中当partitionDiscoveryIntervalMs > 0时启动名为pulsar-split-discovery-executor的守护线程,周期性调用discoverySplits()(对应topic-discovery.interval); - 状态快照:
snapshotState记录已分配分区集合为PulsarSplitEnumeratorState,restoreEnumerator时从 checkpoint 恢复——这正是 2.2.0-beta 修复 "restore 时无法标记 noMoreNewSplits" 与 2.3.12 优化 enumerator API/减少锁调用的落点。
- 分区均匀分配:
PulsarSourceReader(源码):为每个 split 创建独立的PulsarSplitReaderThread(消费线程命名规则为 "Pulsar Source Data Consumer + 分区号",正是 2.3.1 版本 "Set the name of the pulsar consumption thread" 提交的产物),线程通过Handover队列把消息交给 Reader 的pollNext()反序列化并下发。
5.2 游标(Cursor)体系:位点控制的设计
游标是 Pulsar Source 位点控制的核心抽象,按"启动/停止"分为两族,全部位于 source/enumerator/cursor/ 包下:
启动游标(StartCursor)——对应 cursor.startup.mode:
| 枚举值 | 实现类 | 语义 |
|---|---|---|
| EARLIEST | MessageIdStartCursor(earliest 构造) |
从最早未消费位点开始 |
| LATEST | MessageIdStartCursor(latest 构造) |
从最新位点开始 |
| SUBSCRIPTION | SubscriptionStartCursor |
从指定订阅的已提交位点开始,需配合 cursor.reset.mode |
| TIMESTAMP | TimestampStartCursor |
从指定毫秒时间戳开始 |
停止游标(StopCursor)——对应 cursor.stop.mode:
| 枚举值 | 实现类 | 语义 |
|---|---|---|
| NEVER | NeverStopCursor |
无界流式 |
| LATEST | LatestMessageStopCursor |
有界,读到最新消息即止;prepare(pulsarAdmin, partition) 通过 admin API 探测分区当前最新 messageId |
| TIMESTAMP | TimestampStopCursor |
有界,读到指定时间戳即止 |
5.3 精确一次(Exactly-Once)消费链路
Source 侧精确一次依赖 checkpoint 与 Pulsar cursor(订阅位点)协同:
pollNext()在 checkpoint 锁内更新 split 的latestConsumedId(PulsarSourceReader.pollNext);snapshotState(checkpointId)把各 split 最新消费 MessageId 放入pendingCursorsToCommit;- checkpoint 完成时
notifyCheckpointComplete取出该批 cursor 调用committingCursor,由PulsarSplitReaderThread向 Pulsar 提交消费位点(对应 2.3.1 修复的 "consumer ack 异常" 提交)。
故障恢复:Reader 从 PulsarPartitionSplit 快照恢复 split 状态与位点;Enumerator 从 PulsarSplitEnumeratorState 恢复已分配分区。两份状态类均实现了 Serializable 并带 serialVersionUID,这正是 2.3.11 新增 serialVersionUID 缺失检查脚本的原因。
5.4 认证与类加载安全
- 认证:
auth.plugin-class+auth.params通过AuthenticationFactory.create(...)创建 Pulsar 认证对象,未配置时使用AuthenticationDisabled.INSTANCE(PulsarConfigUtil.createAuthentication)。TLS 场景下client.service-url使用pulsar+ssl://协议。文档 FAQ 中示例认证插件类为org.apache.pulsar.client.impl.auth.AuthenticationToken。 - 类加载安全:连接器关闭 client/consumer/producer/admin 时,Pulsar 及其 shaded Netty/Jersey 栈可能从线程上下文类加载器懒解析实现类,因此
PulsarConfigUtil.runWithConnectorClassLoader会在关闭动作期间临时切换回连接器类加载器,避免在引擎线程中发生NoClassDefFoundError。
六、测试与验证体系
仓库为该连接器提供了完整的单元测试与 e2e 测试,可作为理解行为与复现问题的参考:
单元测试(seatunnel-connectors-v2/connector-pulsar/src/test/):
- PulsarMultiTableConfigTest.java:覆盖多表配置解析、全局默认值回退、item 级覆盖、TEXT 拒收、AVRO 必配 schema、topic 重叠拒绝、重复 pattern 拒绝、SUBSCRIPTION 缺 reset mode 拒绝等 12 个场景;
- PulsarSourceReaderRestoreTest.java:验证 Reader 状态恢复;
- MultiTablePartitionDiscovererTest.java:验证多表分区发现与 pattern 重叠确定性路由;
- PulsarConfigUtilTest、PulsarSinkFactoryTest、PulsarSinkWriterTest、PulsarCanalDecoratorTest 等。
端到端测试(seatunnel-e2e/seatunnel-connector-v2-e2e/connector-pulsar-e2e/,基于 Testcontainers 拉起真实 Pulsar 容器):
- PulsarMultiTableIT.java:向两个 topic 生产数据后运行多表→Assert 作业验证读取;
PulsarBatchIT:批式读写;PulsarFormatIT:多格式验证;CanalToPulsarIT:Canal 变更事件链路;PulsarSinkIT:Sink 写入。
七、常见问题(FAQ)
Q1:如何处理分区 Topic 与动态分区发现?
订阅分区 Topic 或使用 topic-pattern 时,SeaTunnel 通过 PulsarAdmin 自动感知分区信息,由 PulsarSplitEnumerator 将分区作为 split 均匀分配给各并发 reader;topic-discovery.interval 控制新分区探测频率。注意有界作业不支持动态发现。
Q2:支持哪些消费位点恢复与订阅模式?
cursor.startup.mode 支持 EARLIEST(最早未消费位点)、LATEST(最新位点)、SUBSCRIPTION(订阅已提交位点,需配 cursor.reset.mode)、TIMESTAMP(指定毫秒时间戳)。消费者在 checkpoint 时同步保存 MessageId,故障时可精准回溯(见 5.3 节)。
Q3:如何连接开启安全认证的 Pulsar 集群?
通过 auth.plugin-class 声明认证插件实现类(如 org.apache.pulsar.client.impl.auth.AuthenticationToken),并在 auth.params 传入 Token 等凭据;若启用 TLS,client.service-url 需使用 pulsar+ssl:// 协议。
Q4:Sink 如何保证精确一次?
semantics = "EXACTLY_ONCE" 时基于 Pulsar 事务 2PC:Writer 侧事务写入、Committer 侧通过 TransactionCoordinatorClient.commit(txnID) 协同提交。前置条件:集群开启事务、transaction_timeout 大于 checkpoint 间隔。
Q5:Sink 支持动态多表路由吗?
支持。多表/整库同步时若未配置全局 topic,PulsarSinkWriter.resolveTopic 会按每行数据的表标识路由到同名 topic;数据无表标识且未配 topic 时任务报配置错误。
Q6:Sink 支持哪些序列化格式?
format 支持 json(默认)、text(可配 field_delimiter)、avro。avro 格式下 schema 由上游行类型自动推导,无需在 Sink 侧额外配置 schema。
八、结语
从 2.2.0-beta 的"基础可用",到 2.3.4 补齐 Sink、2.3.6 引入多表读取、2.3.12 完成 enumerator 语义优化与选项重构,Apache SeaTunnel 的 Pulsar 连接器已经形成一套覆盖批/流、单表/多表、至少一次/精确一次的完整能力矩阵。本文以 connector-pulsar.md 变更日志 为时间轴,串联官方Source/Sink 文档与 connector-pulsar 模块源码,给出了可直接复用的全部配置示例与底层实现依据。在实际使用中,建议优先参考 PulsarSourceOptions.java、PulsarSinkOptions.java 中的默认值与描述信息,并结合本仓库 e2e 测试用例验证连通性后再上线生产环境。