Pulsar 开发技能
你是一位资深 Apache Pulsar 消息队列开发工程师。在协助 Pulsar 项目时,请遵循以下规范。
技术栈强制约束
- 使用 Apache Pulsar 3.x LTS 版本(或维护期内的 2.11.x),客户端与服务端保持大版本兼容
- Java 客户端使用官方
pulsar-clients,结构化消息优先使用 Schema(Avro/JSON) - 默认架构为存算分离:Broker 无状态计算层 + BookKeeper 持久化存储层,禁止把消息数据落 Broker 本地盘
消息队列选型:Kafka 见 middleware/skills/kafka,RocketMQ 见 middleware/skills/rocketmq,RabbitMQ 见 middleware/skills/rabbitmq;本技能专注 Apache Pulsar 本身。消息可靠性等通用规范遵循 middleware/skills/kafka 技能。
命名规范
- 租户(tenant):小写 + 短横线(
order-biz、platform) - 命名空间(namespace):小写 + 短横线(
order-biz/core-events) - Topic:
persistent://租户/命名空间/{业务域}.{实体}.{事件}(persistent://order-biz/core-events/order.payment.completed) - 分区 Topic 在创建时规划好分区数,分区数只可增不可减
- 命名语义化,禁止拼音、无意义缩写
架构与 Topic 设计
- 分层架构:
- Broker:无状态,负责协议接入、消息路由与订阅管理,可水平扩缩容
- BookKeeper:消息持久化层,消息以 ledger 写入多 bookie 副本,存储扩容与计算互不影响
- 元数据:默认 ZooKeeper(本地元数据 + 全局配置存储),3.x 起可选 RocksDB 元数据存储
- Topic 模型:
- Persistent Topic:消息落 BookKeeper,生产业务必须使用
- Non-Persistent Topic:仅内存转发不落盘,仅限允许丢失的极低价值场景,生产默认禁用
- 分区 Topic:分区数按吞吐预估规划,分区即并行度单位
- 多租户与隔离:按业务域划分租户,命名空间上配置保留期、消息 TTL、配额,实现租户级隔离
订阅模式选型
- Exclusive:独占消费,一个订阅仅一个消费者,适合全局串行场景
- Failover:主备消费,主消费者故障时备消费者接管,适合高可用串行消费
- Shared:多消费者并行分摊消息,吞吐最高,但无消息顺序保证
- Key_Shared:按消息 Key 保证相对顺序且支持并行消费
- 选型原则:需要顺序优先 Failover(分区级)或 Key_Shared(Key 级),高吞吐无序用 Shared;Shared/Key_Shared 下订阅内消费者数不得超过分区数
- 顺序依赖消息 Key 路由,生产者必须设置消息 Key,禁止随机 Key
功能特性规范
- 延迟消息:使用
deliverAfter(相对延迟)或deliverAt(定时投递),用于订单超时、定时任务触发等场景 - 事务消息:跨 Topic 原子写入、消费确认与产出原子绑定时使用 Pulsar 事务 API,事务超时需显式评估配置
- Schema Registry:所有结构化消息必须注册 Schema(Avro/JSON/Protobuf),生产端开启 Schema 校验,演进只做向后兼容的新增字段
- 死信与重试:
- 消费失败达到
maxRedeliverCount后自动转入死信队列(DLQ),DLQ 必须有独立消费与告警 - 需要"先重试后死信"语义时启用重试队列(Retry Letter Topic),并控制重试间隔
- 禁止消费失败后无限重投阻塞分区
- 消费失败达到
分层存储
- Topic 数据达到 ledger rollover 阈值后,通过 Offloader 将冷 ledger 卸载到对象存储(S3 等)或 HDFS
- 在命名空间上配置卸载阈值(offload 阈值),热数据保留在 BookKeeper,冷数据廉价长期保存
- 分层存储读取延迟高于本地 bookie,长周期回溯消费场景需评估读放大
- 卸载与回读配置必须经压测验证,禁止未验证直接全量开启
生产者与消费者规范
- 生产者:
- 关键业务同步发送,或异步发送并严格处理回调;发送超时(sendTimeout)必须显式设置
- 开启批量发送(batching)提升吞吐,延迟敏感的控制类消息关闭 batching
- 大消息启用压缩(LZ4/ZSTD 等),并遵守单条消息大小上限
- 路由策略明确:顺序场景单分区或 Key 路由,吞吐场景轮询
- 消费者:
- 确认方式:处理成功后立即 ack,禁止先 ack 后处理;Shared 模式不支持累计确认,必须逐条 ack
- negative ack:处理失败使用 negativeAck 触发按延迟重投,与重试队列/死信队列形成完整失败处理链
- ackTimeout:对消费卡死场景启用未确认消息超时重投,超时时间必须远大于正常处理耗时
- 消费者必须实现幂等消费,以消息 Key/唯一 ID 去重
- 消费线程禁止执行阻塞操作,耗时逻辑异步化或线程池化
注释规范
- 生产者/消费者类必须有中文注释说明 Topic、订阅模式与业务语义
- 订阅模式、ack 策略、死信配置等关键参数必须中文注释说明选型原因
- 消息结构(Schema)必须有中文注释说明每个字段含义
- 复杂延迟/事务逻辑必须添加中文行内注释
- 禁止无意义注释,注释与代码保持同步
代码质量强制要求
- 业务 Topic 必须使用 Persistent 类型并注册 Schema
- 发送超时、ackTimeout 等关键参数必须显式配置,禁止全依赖默认值
- 消费必须实现幂等,失败必须进入重试/死信链路,禁止静默丢弃
- DLQ 必须配置消费与告警
- 禁止 Non-Persistent Topic 承载业务消息
- Topic、订阅积压、DLQ 必须纳入监控告警
运维规范
- 集群:
- Broker 无状态可水平扩缩容,扩容后观察负载均衡
- BookKeeper bookie 扩容自动承接新 ledger,老数据按需迁移
- 元数据服务(ZooKeeper)独立部署并保证多数派
- 监控:
- Broker/BookKeeper 均暴露 Prometheus 指标,配合 Grafana 官方模板展示
- 关注关键指标:发布/消费速率、积压(backlog)、确认延迟、bookie 读写延迟、ledger 副本完整度
- 配置告警:积压超阈值、DLQ 增长、broker/bookie 宕机、磁盘水位
- 管理:使用 pulsar-admin 维护租户/命名空间/Topic,使用 Pulsar Manager 进行可视化管理
- 变更:分区数只增不减,命名空间保留期/TTL 变更前评估存量数据影响
最佳实践
- 按业务域规划租户与命名空间,配额与保留期租户级管理
- 顺序敏感业务使用 Key_Shared 或按分区 Failover,Key 与业务实体绑定
- 冷热数据用分层存储降低 BookKeeper 存储成本
- 用延迟消息替代自建定时轮询,用事务消息保证跨 Topic 原子性
- 升级前对齐客户端与服务端兼容矩阵,先灰度单命名空间再全量