第5章 亲手放消息下水：客户端开发实战

第 5 章 · 亲手放消息下水：客户端开发实战

章节摘要：本章把前四章的原理全部落进可运行的代码。跟一条订单消息从你的指尖出发：生产者怎么发才又快又稳（异步、批量、压缩），消费者怎么接才不丢不乱（订阅、监听、确认），Reader 如何不订阅也能精确读取，Schema 如何给消息立下字段契约。Java 与 Python 双语示例贯穿全章，均给出预期输出。

一条主线

主线进入"施工期"：订单团队的新服务要接入事件流，开发者面临真实的编码决策——发送用同步还是异步？批量开多大？压缩选哪种？消费者用监听还是循环拉取？确认在哪一行调用？本章每节就是一组这样的决策，每个决策都给出演练代码与预期输出。你可以开一台本地 Pulsar，把这章的代码逐段跑通——它们按可运行标准书写。

沿途站点

5.1 生产者实战：异步、批量与压缩

send 的返回语义、异步发送与回调、批量的吞吐与尾延迟权衡、压缩算法的选择依据。这一站的目标是把生产者的每个参数从"配置项"变成"决策"。

5.2 消费者实战：订阅、监听与确认

监听模式与循环拉取两种写法、确认的时机与粒度、重试与死信的客户端配置。这一站把第 3 章的投递语义翻译成具体的代码行。

5.3 Reader 接口与多语言客户端

不加入订阅、自己拨动读取位置的 Reader 接口，适配回放与桥接场景；Java 之外的 Python、Go 客户端长相与习性。这一站补全客户端工具箱。

5.4 Schema：结构化消息的质检标签

让主题带类型：JSON 与 Avro 的声明方式、Schema 兼容性策略如何拦住"改字段毁下游"的事故。这一站把消息从字节数组升级为有契约的数据。

拐点与结论

本章的拐点在 5.1：客户端 API 的绝大多数参数，本质是"延迟、吞吐、可靠性"三者的分配按钮，不存在最优配置，只存在匹配业务的配置。第二个拐点在 5.4：Schema 兼容性检查把"消息契约"从口头约定变成集群强制——这是 Pulsar 相对许多前辈系统在工程治理上最实在的增值。结论：客户端代码的功夫在参数之外，在于你能否说清每个选择换来了什么、放弃了什么。

读完你应该

1. 能写出异步发送加回调的健壮生产者，解释批量与压缩的参数取舍；
2. 能实现监听与循环两种消费模型，正确安放确认、nack 与死信配置；
3. 能用 Reader 实现指定位置的回放读取，说明它与订阅消费的区别；
4. 能用 Python 客户端完成与 Java 等价的收发，理解多语言客户端的行为一致性；
5. 能为业务主题声明 Schema、设置兼容性策略，并演示一次兼容性拦截。

动手环境与本章学法

本章是动手章，环境准备两步就够：本机起一个 Pulsar 单机实例（发行包解压即用），Java 侧建一个普通 Maven 工程引入客户端依赖、Python 侧装客户端包。所有示例按可运行标准书写，跑通它们的价值远大于通读——客户端 API 的手感（异步回调的时序、确认的位置、Schema 拦截的报错形态）只有亲手敲过才长在身上。

学法上建议"改坏再修"：每个示例跑通后，故意改坏一个参数再观察行为——把批量关掉看吞吐差多少、把确认删掉看重投何时来、把字段类型改掉看 Schema 怎么拦。客户端 API 的多数坑（回调漏处理、确认位置错、兼容档位配错）在"改坏"时的报错与延迟现象，就是生产事故的预演。本章每节末尾的要点回顾按"决策加理由"组织，抄进团队的接入规范正好可用。

下一章的接力

代码跑通了，消息在测试环境漂得欢。第 6 章把它搬进生产水域：集群怎么部署、指标怎么看、权限怎么管、函数计算怎么挂上去——航行保障篇，负责让漂流从演示变成生产。