Java项目需在pom.xml中添加pulsar-client 3.3.0（或3.0.8+）依赖，支持BatchReceive及Java 17+；serviceUrl须与Pulsar服务端advertisedAddress严格一致；subscriptionName须全局唯一且subscriptionType按场景选型；务必显式调用.close()释放资源。
Java项目里怎么加Pulsar客户端依赖
直接在pom.xml里加pulsar-client，别只抄旧版本。2026年主流项目建议用3.3.0或3.0.8+——低版本（比如2.8.0）不支持BatchReceive，也缺对Java 17+的完整适配。
- 必须加的依赖：
<dependency><groupId>org.apache.pulsar</groupId><artifactId>pulsar-client</artifactId><version>3.3.0</version></dependency></li> <li>如果要动态查Topic、删订阅、管理命名空间，再补一个<code>pulsar-client-admin
- Spring Boot 3项目更推荐用
pulsar-spring-boot-starter，它自动装配PulsarTemplate和PulsarAdmin，但注意它默认不启用Functions Worker
serviceUrl写错是启动就报错的头号原因
serviceUrl不是随便填pulsar://localhost:6650就完事。本地单机调试可以这么写，但一旦进Docker、NAT、云主机，advertisedAddress没配对，Java客户端连得上却收不到消息——因为Broker告诉客户端“去172.18.0.3:6650拉”，而你的本机根本访问不了那个内网IP。
- 确认Pulsar服务端的
conf/standalone.conf或broker.conf里已设advertisedAddress=192.168.1.101（换成你宿主机真实IP） - Java代码里
serviceUrl必须和这个IP一致，不能写localhost或127.0.0.1 - 集群模式下，
serviceUrl可写多个地址，用逗号分隔：pulsar://10.49.196.30:6650,10.49.196.31:6650 - 如果Pulsar启用了TLS或认证（如JWT），
serviceUrl得换pulsar+ssl://...，还得额外传Authentication实例
消费者订阅名和订阅类型选错会导致消息丢或重复
Java里subscriptionName不是随便起个名字就行，它是Pulsar做消息归属和重投的关键标识；subscriptionType选错，轻则消费卡死，重则同一消息被多个实例重复处理。
-
Shared：多个Consumer实例共享一个订阅，适合水平扩展场景，但ack必须显式调用，否则消息不会被删除 -
Exclusive：只允许一个Consumer连上该订阅，其余连接会失败，适合强顺序要求 -
Failover：主备模式，只有一个Active Consumer，其他待命，适合高可用但不追求吞吐 - 务必保证
subscriptionName在同一个Topic下全局唯一，否则历史未ack消息会被新Consumer误读
关闭资源不规范会让进程hang住甚至OOM
Pulsar Java SDK底层用Netty和BookKeeper Client，不显式close()的话，线程池、连接池、内存缓冲区全留在后台——Spring Boot应用重启时常见java.lang.OutOfMemoryError: Direct buffer memory，根源往往在这。
立即学习“Java免费学习笔记（深入）”；
- Consumer/Producer创建后，必须在业务结束时调用
.close()；不要依赖GC -
PulsarClient生命周期应与应用一致，整个进程只建一次，用完不关，但别频繁重建 - 用Spring管理时，建议用
@PreDestroy或DisposableBean钩子确保client.close() - 异步消费（
receiveAsync()）必须自己写递归回调，漏掉receiveAsync()续订就会停收
advertisedAddress、subscriptionName、close()这三个点上。 
