5.3 Reader 接口与多语言客户端

5.3 Reader 接口与多语言客户端

本节摘要：Reader 是消费者的"旁听席"：不加入任何订阅、不推进游标、自己指定从哪读起。本节讲清它与订阅消费的本质区别与适用场景，并用 Java 与 Python 把同一段收发逻辑各写一遍——多语言客户端的行为一致性，正是第 2 章客户端层设计的兑现。

不订阅也能读：Reader 的旁听席逻辑

订阅消费者的每一次读取都在推进游标，"读过"这件事会被系统记账。但有一类读取恰恰不想记账：回放历史给新上线的服务预热缓存、把主题数据搬运到另一个系统、调试时从头扫一遍消息。这些场景要的是"只读不签收、进度我自己管"——这就是 **Reader（读取器）**的定位。

Reader 与订阅消费的差别集中在三处。其一，无游标：Reader 不产生订阅名，读到哪里完全由调用方持有（拿 MessageId 做书签）；其二，起点自选：最早、最新、或任意一个 MessageId——这让"从某个坐标开始回放"成为一行参数；其三，无确认：读过的消息不会被标记，同一主题可以被任意多个 Reader 反复读。

一、Java Reader：一段带书签的回放

场景：数仓服务每天凌晨要从"昨天零点附近"的消息开始回放进湖。Reader 的书签机制正好胜任：

// 从最早的 MessageId 创建 Reader
Reader<String> reader = client.newReader(Schema.STRING)
        .topic("persistent://trade-order/transaction/order-events")
        .startMessageId(MessageId.earliest)      // 也可用 latest 或指定坐标
        .create();

String bookmark = null;                          // 书签：进度自己持有
while (reader.hasMessageAvailable()) {
    Message<String> msg = reader.readNext(1, TimeUnit.SECONDS);
    if (msg == null) break;
    loadToWarehouse(msg.getValue());             // 自行处理，无签收动作
    bookmark = msg.getMessageId().toString();    // 记下坐标
}
System.out.println("回放到坐标: " + bookmark);
// 下次想从断点续读：newReader().startMessageId(
//     MessageId.fromByteArray(decode(bookmark))).create()
​

与订阅消费对照着看就明白各自的领地：订阅消费问"轮到我没"（系统记账），Reader 问"我想从哪读"（自己记账）。需要重投、死信、共享并行这些投递语义的场景老实用订阅；需要"游客式任意读"的场景用 Reader。还有一个隐蔽用法值得知道：用 Reader 读死信主题做检查修复，比临时建订阅更干净——不留游标、不留订阅残留。

二、Python 客户端：同一套心智的另一种拼写

Pulsar 客户端在 Java、Python、Go、C++ 上的概念完全同构，只是拼写不同。同一段"发带键消息、共享订阅消费"的逻辑，Python 版本长这样：

import pulsar

client = pulsar.Client('pulsar://localhost:6650')

# 生产者：与 Java 版相同的参数语义
producer = client.create_producer(
    'persistent://trade-order/transaction/order-events',
    batching_enabled=True,
    batching_max_publish_delay_ms=10,
)

for i in range(100):
    producer.send(
        ('{"orderId":"%s","amount":9900}' % i).encode(),
        properties={'trace-id': 'py-0001'},
        partition_key='order-%s' % i,          # 消息键，路由与顺序语义一致
    )
producer.close()

# 消费者：共享订阅
consumer = client.subscribe(
    'persistent://trade-order/transaction/order-events',
    subscription_name='risk-scan-py',
    subscription_type=pulsar.SubscriptionType.Shared,
)
while True:
    msg = consumer.receive(timeout_millis=5000)
    try:
        print('处理:', msg.data(), '键:', msg.partition_key())
        consumer.acknowledge(msg)
    except Exception:
        consumer.negative_acknowledge(msg)
​

逐段对照 Java 版会发现一个值得感激的事实：批量窗口、消息键、订阅模式、确认与 nack，语义逐项对应，参数名直译。工程上的意义在第 2 章埋过伏笔——协议由客户端层统一封装，各语言只是外壳。团队里 Java 主力、脚本侧用 Python 写数据工具时，两边的消息行为可以做到逐字节可预期。

⚠️ 常见坑：多语言混用时最常翻车的是 Schema（下一节的主角）。Java 侧声明了 Avro Schema 的主题，用未带 Schema 的 Python 裸客户端发字节数组，会直接被服务端拒绝——这不是兼容性缺陷，而是 5.4 节契约机制在正常工作。排查思路先查 Schema 再查网络。

Go 与 C++：工具箱里剩下的扳手

Go 客户端在云原生工具链里常见（运维机器人、轻量网关），C++ 客户端则是性能敏感与存量系统对接的老兵。四门语言的分工在团队里通常自然形成：Java 承载业务主干，Python 写数据与运维脚本，Go 做平台小工具，C++ 留给历史系统。值得写进团队规范的是"语言选择不改变行为"的验证习惯——跨语言接入同一主题时，先各发一条探针消息互相消费一次，确认键、属性、Schema 的语义在两端表现一致，再正式接入。探针成本一分钟，换来的是对"协议统一"的实证信任。

最后提醒一个所有语言通用的客户端纪律：连接与生产者消费者对象都是线程安全的长寿命对象，全局复用一份即可，频繁创建销毁既是性能浪费，还可能触发服务端的连接限流。见过最多的反模式是"每发一条消息建一次客户端"——把它写进代码评审的必查项。

本节要点回顾

• Reader 无游标、无确认、起点自选，是"只读不记账"的旁听席；
• 回放、桥接搬运、死信检查是 Reader 的三类典型场景；
• Reader 的进度书签是 MessageId，断点续读靠坐标解码；
• 多语言客户端概念同构、参数直译，行为一致性来自统一协议层；
• 裸客户端对带 Schema 主题的写入会被拒绝，排查先查契约。

下一站把消息从"字节数组"升级成"有契约的数据"：Schema 的声明、演进与兼容性拦截。