Zookeeper客户端开发实战：从Java API入门到分布式锁与Watcher机制

我最早接触Zookeeper是在一次Kafka集群扩容事故里，那会儿消费端莫名其妙全部断开，排查到最后发现是Zookeeper会话超时参数没配好。从那以后我就意识到，搞大数据的人可以不会写Zookeeper源码，但绝对不能不会写Zookeeper客户端。这篇博文就围绕“Zookeeper客户端开发”这个主题，把Java API在真实大数据项目里的用法从入门到实战完整过一遍，适合刚接触ZK的Java开发，也适合那些已经在Hadoop、Kafka项目里用了ZK但一直没搞懂客户端细节的同学。

文章里所有代码都是我在实际项目里跑过的，结合Hadoop和Zookeeper整合、分布式环境搭建这些真实场景来讲。我尽量把每个API背后的设计逻辑讲明白，而不只是贴一段能跑的通代码。毕竟只在本地连一下ZK节点，和在生产环境处理千万级临时节点的会话管理、监听恢复、锁竞争，完全是两码事。

1. 项目定位与整体设计思路

1.1 为什么大数据项目离不开Zookeeper

先聊一个很多人会问的问题：文件系统有HDFS，协调任务有Yarn，数据库有HBase，为什么还需要一个Zookeeper？我的理解是，上面这些组件解决的是“数据存哪里、计算怎么跑”的问题，但分布式系统里还有一个更基础的问题——多个进程之间如何达成共识。

举个最简单的例子：HDFS的NameNode是主备部署的，两个节点都要抢Active状态，到底谁说了算？如果靠数据库做选主，数据库本身又是单点。ZK在这里就是那个裁判，用临时节点加Watcher机制，让备节点能实时感知主节点是否存活。同理，Kafka的Controller选举、HBase的HMaster选举，都是ZK在背后支撑。

所以Zookeeper的定位从来不是存储系统，而是一个分布式协调服务。它提供的是命名服务、配置管理、分布式锁、集群成员管理等能力。数据是存在内存里的，读写快，但容量小，这也决定了ZK的数据模型必须设计成类似文件系统的树形结构，节点不能存大块数据，默认上限是1M。

在大数据项目里，ZK的典型应用场景大概是这几个：

• 集群选主：Hadoop HA、Kafka Controller、HBase HMaster都会用到
• 配置集中管理：把公共配置写到ZK节点，客户端动态监听，配置变更实时生效
• 分布式锁：用临时顺序节点实现公平锁，解决多进程并发写同一资源的冲突
• 服务注册与发现：服务启动时注册临时节点，下线自动删除

这几个场景里，客户端开发的核心就两件事：操作节点和监听变化。理解了这两点，ZK的Java API基本就掌握了一大半。

1.2 原生Java API还是Curator：到底怎么选

Zookeeper官方提供了Java客户端库，也就是zookeeper这个artifact下的一系列API。这个原生API功能完整，但用起来比较“裸”，很多细节需要自己处理，比如：

• Watcher只触发一次，触发后要重新注册
• 连接断开时抛ConnectionLossException，需要重试
• 没有提供锁、Leader选举这些高层封装

后来Apache Curator出现了，它把上面这些脏活累活都封装好了，提供了CuratorFramework、Recipe（分布式锁、Leader选举、缓存）等高级特性。网上很多教程也推荐直接用Curator。

但我的建议是，如果你是初学者，先老老实实把原生API学明白。原因很简单：Curator内部也是调用原生API，如果你不懂Watcher底层是怎么实现的，用Curator的NodeCache或LeaderSelector时遇到问题会很懵，因为你不清楚它到底在哪些节点注册了监听，监听失效后发生了什么。我自己带项目组时，要求新人必须能手写原生API的节点CRUD，再说Curator。

还有一个现实因素是，很多公司线上ZK的版本是3.4.x或者3.5.x，而Curator对不同ZK版本有兼容性要求。用原生API就没有这个烦恼，只要依赖的版本和集群版本做好区分就行。

这篇文章后续的代码都以原生Java API为主，在最后一章适当提一下生产环境如何迁移到Curator。这样既能理解底层原理，又知道实际工程该用什么。

2. 环境准备与客户端依赖引入

2.1 JDK、Maven依赖和版本怎么选

先说环境。我本地用的JDK是1.8，这和项目里大部分大数据组件的版本是匹配的。Zookeeper客户端本身对Java版本要求不高，3.5.x版本的客户端在JDK8上跑得很稳，但如果你用的是ZK 3.6及以上，建议至少用JDK8u231以后的版本，避免某些TLS相关的兼容问题。

Maven项目里引入依赖很简单：

<dependency> <groupId>org.apache.zookeeper</groupId> <artifactId>zookeeper</artifactId> <version>3.5.9</version> </dependency>

有个非常容易踩的坑是：zookeeper这个依赖会传递引入log4j、slf4j等日志组件，如果你的项目里已经用了logback或者其他日志实现，可能会出现冲突。建议在引入时做一下exclusion：

<dependency> <groupId>org.apache.zookeeper</groupId> <artifactId>zookeeper</artifactId> <version>3.5.9</version> <exclusions> <exclusion> <groupId>org.slf4j</groupId> <artifactId>slf4j-log4j12</artifactId> </exclusion> <exclusion> <groupId>log4j</groupId> <artifactId>log4j</artifactId> </exclusion> </exclusions> </dependency>

另外，如果你用了Curator，还需要单独引Curator的依赖，这里先不展开。

关于ZK服务端的版本选择，我建议测试环境用3.5.x，生产环境看社区生态。3.4.x已经逐渐退出历史舞台了，3.5.x引入了SSL支持和容器节点，3.6.x增加了更多监控指标。新项目直接用3.5.9或3.6.x都行，但要注意客户端版本和服务端版本不要差以太远，否则可能出现协议兼容问题。

2.2 本地快速跑一个单机ZK服务端

写客户端之前，本地至少要有一个ZK服务端。生产环境是分布式集群部署，初学者先在本地跑单机就够了。下载ZK安装包后，修改conf/zoo.cfg：

tickTime=2000 dataDir=/tmp/zookeeper/data clientPort=2181 initLimit=10 syncLimit=5

然后启动：

bin/zkServer.sh start

启动后用bin/zkCli.sh -server 127.0.0.1:2181连一下，能进到ZK命令行界面就算成功。我习惯先用zkCli确认服务端OK，再开始写Java客户端，这样可以避免两边同时出问题都不知道该排查谁。

你可能会问，tickTime、initLimit、syncLimit这些参数什么意思？简单说：

• tickTime：ZK的最小时间单元，默认2000毫秒，其他时间参数都基于它计算
• initLimit：Follower启动时能容忍的同步最长等待时间，单位是tick
• syncLimit：Follower和Leader之间请求响应的最长超时时间
• dataDir：快照日志存储路径，ZNode数据会定期落盘

这些参数在单机模式下影响不大，但部署集群时必须认真调。比如网络状况差的机房，initLimit如果设得太小，Follower启动时可能一直初始化失败，表现就是节点起不来。我帮别人排查过一次这个问题，最后就是把这个参数从5调到了10。

2.3 最小可运行实例：从连接ZK到创建节点

环境准备好以后，写一个最小可运行的Java类。这个类做的事情很简单：连接ZK、创建根路径下的一个节点、读取数据、关闭连接。但麻雀虽小五脏俱全，它涵盖了客户端开发的完整链路。

import org.apache.zookeeper.*; import org.apache.zookeeper.data.Stat; import java.util.concurrent.CountDownLatch; public class ZkQuickStart { // 连接字符串格式：host:port，多个实例用逗号分隔 private static final String ZK_ADDRESS = "127.0.0.1:2181"; private static final int SESSION_TIMEOUT = 5000; public static void main(String[] args) throws Exception { CountDownLatch connectedLatch = new CountDownLatch(1); // 创建ZooKeeper客户端，建立会话 ZooKeeper zooKeeper = new ZooKeeper(ZK_ADDRESS, SESSION_TIMEOUT, watchedEvent -> { if (watchedEvent.getState() == Watcher.Event.KeeperState.SyncConnected) { // 会话建立成功 connectedLatch.countDown(); } }); // 等待连接建立 connectedLatch.await(); // 创建节点：路径、数据、ACL、创建模式 String path = zooKeeper.create("/myApp", "hello zk".getBytes(), ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode.PERSISTENT); System.out.println("create node: " + path); // 读取节点数据 Stat stat = new Stat(); byte[] data = zooKeeper.getData("/myApp", false, stat); System.out.println("read data: " + new String(data)); System.out.println("version: " + stat.getVersion()); // 关闭连接 zooKeeper.close(); } }

这段代码看着简单，但有几个细节必须说明。ZooKeeper构造函数里的Watcher参数，传的是默认Watcher，它主要负责会话状态变更事件，比如SyncConnected、Expired等。而后面我们讲getData、exists这些API里传入的Watcher，是节点事件监听器，两者不是一回事，新手很容易搞混。

OPEN_ACL_UNSAFE表示这个节点不做权限控制，所有人都能读写。生产环境一般不这么干，但这个ACL在开发阶段很方便。

CreateMode.PERSISTENT表示持久节点，断开连接后节点还在。还有EPHEMERAL临时节点、PERSISTENT_SEQUENTIAL持久顺序节点、EPHEMERAL_SEQUENTIAL临时顺序节点，后面展开讲。

这段代码跑通以后，恭喜你，Zookeeper客户端开发的入门关卡已经过了。下面进入真正的核心API实战。

3. 核心API实战：节点操作、监听机制与异步回调

3.1 节点增删改查：每个参数都要知道为什么

ZooKeeper的节点操作和文件系统很像，但细节上有不少差异。我逐个说。

创建节点

create方法有多个重载，核心参数是路径、数据、ACL和创建模式。

// 创建一个临时节点 String path = zooKeeper.create("/myApp/tmp", "temp".getBytes(), ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode.EPHEMERAL);

注意一点：ZK的节点路径不支持递归创建，也就是说/myApp不存在时，直接用create("/myApp/tmp")会抛NoNodeException。所以要么从根路径一级一级创建，要么在3.5+版本用create的withParents特性（Curator的creatingParentContainersIfNeeded）。

还有一个常见需求是同时创建多个层级节点，比如同时创建/app/config/db。原生API不能一次性完成，需要写循环。Curator里通过creatingParentsIfNeeded()一行搞定。这也是为什么生产环境用Curator会舒服很多。

读取数据

getData方法返回节点的数据字节数组，同时通过Stat对象带回各种元信息，包括版本号、事务ID、子节点数等。

Stat stat = new Stat(); byte[] data = zooKeeper.getData("/myApp/appName", false, stat);

这里的boolean参数是watch，表示是否注册Watcher。我一般习惯传false，然后用显式的Watcher，因为直接传true等于注册了一个很难精确管理的默认Watcher，在复杂监听场景下容易乱。

更新数据

Stat updateStat = zooKeeper.setData("/myApp/appName", "newVersion".getBytes(), stat.getVersion());

第三个参数是期望的版本号，用于乐观锁控制。如果服务端版本号和本地版本不一致，会抛BadVersionException。这里的设计逻辑很值得琢磨：ZK为什么用版本号而不是时间戳来做并发控制？因为在分布式环境下，服务器时间本身不可靠，而版本号是单调递增且在集群内一致同步的，用它判断冲突才是最准确的。

如果你不关心并发控制，这里传-1表示强制更新，但生产环境不推荐。

删除节点

zooKeeper.delete("/myApp/tmp", -1);

和setData一样，第二个参数是版本号，-1表示不校验版本。删除还有个大坑：节点有子节点时不能直接删除。你需要先递归删除所有子节点，再删父节点。原生API没有提供递归删除方法，得自己写。这也是Curator里deletingChildrenIfNeeded()存在的原因。

检查节点是否存在

Stat existsStat = zooKeeper.exists("/myApp", true);

如果节点存在返回Stat对象，不存在返回null。注意这个API和getData的区别：getData在节点不存在时会抛KeeperException.NoNodeException，而exists不抛异常。所以判断节点是否存在，用exists更合适，不要用getData去try catch。

我把节点操作的核心要点整理成一张表，方便对照记忆：

操作	异常情况	版本控制	是否需要递归处理
create	节点已存在抛NodeExistsException	不涉及	父目录需先存在
getData	节点不存在抛NoNodeException	不涉及	不涉及
setData	节点不存在抛NoNodeException	支持版本校验	不涉及
delete	节点不存在抛NoNodeException	支持版本校验	有子节点则删除失败
exists	不会抛异常	不涉及	不涉及

3.2 Watcher监听机制：一次性触发这件事必须搞明白

Watcher是ZK客户端开发里最容易出问题的点，没有之一。

先看一个正确的监听注册。假设我们要监听/myApp/appName这个节点的数据变化：

Stat stat = zooKeeper.exists("/myApp/appName", event -> { if (event.getType() == Watcher.Event.EventType.NodeDataChanged) { System.out.println("data changed!"); // 重新读取数据 try { byte[] data = zooKeeper.getData("/myApp/appName", false, null); System.out.println("new data: " + new String(data)); } catch (Exception e) { e.printStackTrace(); } } });

这里有个很隐蔽的坑：Watcher只触发一次。也就是说，上面注册的Watcher在第一次NodeDataChanged事件触发以后，就自动失效了。如果你想持续监听节点变化，必须在回调里重新注册Watcher，也就是再次调用exists或getData并传入同样的Watcher。

看下面这个改进版代码：

public void watchNode(String path, ZooKeeper zk) throws Exception { Stat stat = zk.exists(path, event -> { if (event.getType() == Watcher.Event.EventType.NodeDataChanged) { System.out.println("data changed"); try { byte[] data = zk.getData(path, false, null); System.out.println("new data: " + new String(data)); // 重新注册监听，否则只触发一次 watchNode(path, zk); } catch (Exception e) { e.printStackTrace(); } } }); }

为什么ZK要这样设计？我想了很久，最后在官方文档里找到答案：ZK的Watcher是基于客户端与服务端之间的会话通道实现的。如果Watcher持续有效，客户端需要不断维护Watcher注册表，服务端也要在每个节点上维护Watcher列表，这会消耗大量内存。一次性触发机制让服务端能够及时清理无用的Watcher，同时也迫使业务方思考“监听后下一步做什么”。

但在工程实践里，自己写重新注册逻辑很容易漏，比如回调线程抛了异常，Watcher就没法重新注册，业务会静默失效。所以生产环境一般推荐使用Curator的NodeCache或PathChildrenCache，它们内部帮你处理了重注册的问题。不过理解原生机制仍然是基本功——只有你知道Watcher是一次性的，才能理解为什么Curator要设计cache这种模式。

除了数据变化，Watcher还能监听子节点变化和节点删除：

// 监听子节点变化 List<String> children = zk.getChildren("/myApp", event -> { if (event.getType() == Watcher.Event.EventType.NodeChildrenChanged) { System.out.println("children changed!"); // 重新获取子节点列表 } }); // 监听节点删除 Stat stat = zk.exists("/myApp/appName", event -> { if (event.getType() == Watcher.Event.EventType.NodeDeleted) { System.out.println("node deleted!"); } });

还有一类Watcher关注的是会话状态变化，比如连接断开、会话过期。这类Watcher在创建ZooKeeper对象时传入，适合做重连逻辑。会话过期时，ZK会清除该会话创建的所有临时节点，这个特性是分布式锁能自动释放的基础。

3.3 异步回调：不要让网络延迟卡住你的主线程

前面所有示例用的都是同步API，比如create调用后会阻塞直到服务端返回结果。这在数据量小的场景下问题不大，但如果你的应用需要高频操作ZK（比如每秒创建几百个临时节点），同步调用会让主线程大量阻塞在等待网络上。

ZK提供了完整的异步API，核心思路是传入一个AsyncCallback回调对象，操作完成后异步通知：

zooKeeper.create("/async/node", "data".getBytes(), ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode.PERSISTENT, (rc, path, ctx, name) -> { if (rc == KeeperException.Code.OK.intValue()) { System.out.println("异步创建成功: " + name); } else { System.out.println("异步创建失败: " + rc); } }, "context data");

回调参数里的rc是返回码，path是操作路径，ctx是你传入的上下文对象，name是实际创建的节点路径（顺序节点时会带上序号）。

异步API用了KeeperException.Code里的状态码，OK是0，NONODE是-101，NODEEXISTS是-110。排查问题时，看到这些负数不要慌，对照KeeperException.Code枚举就能知道原因。

异步回调的执行线程是ZooKeeper内部的一个线程池，并不是你的业务线程。所以回调里如果有耗时的业务操作，建议用你自己的线程池去处理，避免阻塞ZK的IO线程：

ExecutorService executor = Executors.newFixedThreadPool(4); zooKeeper.getData("/async/node", false, (rc, path, ctx, data, stat) -> { executor.submit(() -> { System.out.println("回调里处理业务：" + new String(data)); }); }, null);

异步API在客户端注册Callback时，如果回调实现里又要调用ZK API，注意不能再用同步版本的getData，否则会抢占同一个IO线程池，可能互相等待造成死锁。这个坑我踩过一次，当时整个ZK客户端线程全部卡住，线上应用看起来像挂了一样。建议回调内再操作ZK时，要么也用异步API，要么把操作丢到一个独立的线程池里。

3.4 一键搞定客户端连接对象初始化

写了好几次new ZooKeeper(...)之后，我建议你封装一个客户端工具类，把连接管理、重连状态监听统一处理。这里给一个基本的封装思路：

public class ZkClientManager { private ZooKeeper zk; private final CountDownLatch connectedSignal = new CountDownLatch(1); public ZkClientManager(String address, int sessionTimeout) throws Exception { this.zk = new ZooKeeper(address, sessionTimeout, event -> { if (event.getState() == Watcher.Event.KeeperState.SyncConnected) { connectedSignal.countDown(); } else if (event.getState() == Watcher.Event.KeeperState.Expired) { // 会话过期，临时节点全部被清理，需要重新建立会话 try { this.zk.close(); } catch (Exception e) { // ignore } this.zk = new ZooKeeper(address, sessionTimeout, event2 -> { System.out.println("重新建立会话"); }); } }); connectedSignal.await(); } public ZooKeeper getZk() { return zk; } public void close() throws InterruptedException { zk.close(); } }

注意会话过期和连接断开的区别。连接断开（Disconnected）只是网络暂时不可通，会话还在服务端保留，重连后可以继续用。但会话过期（Expired）意味着服务端已经销毁了会话，必须重新创建ZooKeeper实例。很多人在写重连逻辑时没区分这两者，导致会话过期后所有临时节点的监听全部失效，业务静默出现故障。

4. 分布式环境下的高级实战：锁、会话与大数据整合

4.1 用临时顺序节点实现分布式锁

先讲一个日常开发中最常遇到的场景：多个应用实例同时处理同一批订单，需要保证只有一个实例能拿到处理权。这时候用ZK实现分布式锁比用数据库锁更合适，因为它天然支持多进程互斥，且客户端可以自动释放。

ZK实现分布式锁的经典方案是：临时顺序节点 + Watcher监听前一个节点。

核心逻辑是：

1. 在/lock路径下创建临时顺序节点，比如/lock/lock_000000001
2. 获取/lock下所有子节点
3. 如果自己创建的节点是所有子节点中最小的，就认为自己拿到了锁
4. 如果没有拿到锁，监听比自己的序号小一位的那个节点，等待它删除
5. 前一个节点删除后，重新检查自己是否是最小节点

为什么用临时顺序节点？临时节点保证客户端会话断开后自动删除，避免锁永远不会释放；顺序节点让竞争节点按顺序排队，每个节点只需要监听前一个节点，不会出现“惊群效应”。

代码核心部分：

public class ZkDistributedLock { private final ZooKeeper zk; private final String lockPath; private String currentNodePath; private String waitPath; public ZkDistributedLock(ZooKeeper zk, String lockPath) { this.zk = zk; this.lockPath = lockPath; } public void lock() throws Exception { // 创建临时顺序节点 currentNodePath = zk.create(lockPath + "/lock_", new byte[0], ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode.EPHEMERAL_SEQUENTIAL); // 获取所有子节点并排序 List<String> children = zk.getChildren(lockPath, false); Collections.sort(children); int currentIndex = children.indexOf(currentNodePath.substring(lockPath.length() + 1)); if (currentIndex == 0) { // 自己是最小节点，拿到锁 System.out.println("get lock: " + currentNodePath); return; } // 监听前一个节点 waitPath = lockPath + "/" + children.get(currentIndex - 1); CountDownLatch latch = new CountDownLatch(1); Stat stat = zk.exists(waitPath, event -> { if (event.getType() == Watcher.Event.EventType.NodeDeleted) { latch.countDown(); } }); if (stat != null) { // 前一个节点存在，等待它删除 latch.await(); } // 前一个节点已删除，重新获取锁 System.out.println("get lock after wait: " + currentNodePath); } public void unlock() throws Exception { zk.delete(currentNodePath, -1); zk.close(); } }

这个实现有两个细节需要强调。第一，exists判断前一个节点时，如果返回null，说明前一个节点刚好被删除，这时候不需要等待，直接自认为拿到锁。第二，创建顺序节点后，子节点列表里既有自己也有其他客户端创建的节点，排序后通过indexOf就能确定自己的位置。标准库的Collections.sort对字符串排序时，lock_10会排在lock_9前面，但因为创建顺序节点时ZK保证序号是递增补零的（如lock_0000000010），所以排序结果没问题。

分布式锁如果只做互斥，用Redis也可以。但ZK锁的优势在于不用设置过期时间来防死锁，临时节点天然处理了客户端宕机的情况。代价是性能不如Redis快，每加一次锁至少要写节点、读节点、监听节点三次网络操作。所以在并发量非常高的场景下，我会优先考虑Redis；在需要绝对可靠互斥的场景（比如选主），ZK更稳妥。

4.2 会话超时、临时节点和心跳：三者的关系必须理顺

ZK客户端与服务端的连接是通过Session来维护的。Session有一个超时时间，由客户端在构造ZooKeeper对象时传入，例如：

new ZooKeeper(zkAddress, 5000, watcher);

这里的5000毫秒就是sessionTimeout。客户端和服务端会协商一个最终的有效超时时间，范围在服务端配置的minSessionTimeout和maxSessionTimeout之间。如果你的服务端没配这两个参数，默认是tickTime的2倍和20倍，也就是4秒到40秒（默认tickTime=2000时）。

为什么会话超时时间这么重要？因为它决定了ZK容忍客户端暂时失联的最大时间：

• 会话超时间内，客户端和服务端断了，重连回来后会话仍然有效，临时节点保留
• 超过超时时间没心跳，服务端判定会话过期，销毁该会话下所有临时节点
• 会话过期后，客户端再次接入，收到的是SessionExpiredException

这个机制用在分布式锁里非常好用：如果拿锁的进程突然宕机了，它的临时节点会在会话超时后被自动清理，锁自动释放。但你要注意，“自动释放”并不是立刻的，中间有最多一个sessionTimeout的延迟。如果你的业务对锁释放延迟很敏感，就要把sessionTimeout配小一点，比如3000毫秒。

反过来，sessionTimeout也不能太小。如果网络经常抖动，会话还没恢复就超时过频，会导致临时节点频繁被创建和删除，对ZK集群压力很大。我见过一个极端案例，有人把sessionTimeout配成1000毫秒，然后网络间歇性故障，ZK集群每秒都在处理大量会话创建和临时节点清理，CPU直接打满。

生产环境的经验值是：sessionTimeout设置在3000到10000毫秒之间，根据网络状况和业务对锁延迟的容忍度来选。网络好、对锁并发敏感的项目用5000左右；网络一般、业务容忍度高的用10000也行。

ZK客户端还有一个心跳机制值得了解。客户端以每tickTime/3的间隔发送心跳（实际是Ping请求），服务端在tickTime内没有收到心跳就认为连接可能断了。心跳是自动发的，不需要业务代码干预，但如果你在Java里看到很多Ping请求，不要以为是异常，那是正常的保活行为。

4.3 Hadoop和Zookeeper整合实战：到底整合了个啥

很多人学ZK的时候，听到“Hadoop和Zookeeper整合”就觉得是不是要把ZK接到HDFS存储上，其实完全不是。ZK在Hadoop生态里主要做HA和元数据协调。

以HDFS为例，NameNode有Active和Standby两个节点。两个节点都往ZK注册一个临时节点表示自己是Active，但ZK的机制决定了同一路径下只能有一个节点创建成功。抢到创建的节点就是Active，另一个自动成为Standby。Active节点异常宕机后，临时节点过期消失，Standby通过Watcher感知到变化，立刻尝试创建同一个节点上位。

这个流程里涉及的东西不多，客户端要做的事也很集中：

1. HDFS启动时，NameNode调用ZK API创建临时节点
2. 监听该节点的存在性
3. Active节点的临时节点消失后，Standby竞争创建

Kafka也是类似，在ZK里注册broker信息，Controller选举同样靠临时节点实现。你在Kafka日志里看到的/brokers/ids/0其实就是ZK上的节点路径。

实际操作层面，以Hadoop 3.x为例，core-site.xml里有几个关键配置：

<property> <name>ha.zookeeper.quorum</name> <value>zk1:2181,zk2:2181,zk3:2181</value> </property>

这个配置指定了ZK集群地址。然后hdfs-site.xml里配置名称服务的ID和NameNode的ID。配置完以后，HDFS内部自己就会用ZK客户端库去抢Active节点，完全不用业务代码介入。

有人问，既然Hadoop内部封装好了，我们还需要学ZK客户端吗？当然需要。你在排查HDFS的ActiveNameNode切换异常时，如果不懂ZK的临时节点和会话机制，根本不知道从哪下手。我在生产环境遇到过一个问题：NameNode节点本身没挂，但ZK会话超时了，临时节点被清掉，导致HA切换。最后检查发现是ZK集群有节点GC导致整个集群抖动，会话集体过期。如果看不懂客户端日志里的Session expired，这个问题会排查得非常痛苦。

5. 常见问题与排查技巧实录

5.1 异常速查表：看到报错知道该怎么办

ZK客户端开发中最常见的问题，我整理成一张表，按频率排序，如果你在生产里碰到类似报错，直接对号入座。

异常	出现场景	根本原因	解决方向
ConnectionLossException	任意操作	客户端与服务端连接断开了	检查网络、查看ZK集群状态、重试操作
SessionExpiredException	任意操作	会话已过期，临时节点已被清理	重新创建ZooKeeper实例，重新注册
NoNodeException	create、getData、delete	操作的节点不存在	检查路径，父节点是否已创建
NodeExistsException	create	节点已存在	先exists判断再创建，或容忍该异常
BadVersionException	setData、delete	传入的版本号和服务端不一致	重新读取最新Stat，用最新版本号重试
KeeperException.ConnectionClosedException	任意操作	ZooKeeper对象已经close	检查资源生命周期，避免用已关闭的客户端

其中ConnectionLossException是最常见的，因为它可能在网络瞬断、ZK节点宕机、GC停顿等五花八门的情况下出现。处理它的思路是重试，但要注意不能无限重试。我一般建议最多重试3次，每次间隔指数退避，比如100ms、200ms、400ms。如果重试3次还失败，就抛错让上游感知，而不是闷头重试把线程占死。

SessionExpiredException则不能简单重试。它代表会话已经没了，临时节点已经全部被清理，如果你用原来的ZooKeeper实例继续操作，会一直失败。正确的做法是重新new一个ZooKeeper，再用新的实例去做业务操作。

5.2 生产环境客户端连接的三个配置细节

除了异常处理，启动生产环境的ZK客户端时，有几个配置值得专门说一下。

连接字符串的顺序

连接字符串可以写多个ZK节点，比如：

String address = "192.168.1.10:2181,192.168.1.11:2181,192.168.1.12:2181";

客户端会按顺序尝试连接这些地址。所以建议把离客户端最近的节点放在前面，可以减少连接耗时。如果第一个节点挂了，会自动尝试下一个。

最大连接重试次数

如果你用原生API，重连逻辑得自己写。ZooKeeper对象内部对连接中断的处理是：自动尝试重连，直到会话超时。所以你的业务代码需要注意，一次操作失败后，给客户端一点时间恢复连接再重试，不要死循环调用。

如果你用Curator，RetryPolicy可以配置得更精细。比如：

RetryPolicy retryPolicy = new ExponentialBackoffRetry(1000, 3, 5000);

表示初始等待1秒，最多重试3次，最大等待5秒。这个策略的好处是避免了同步重试带来的请求风暴。

watch数量过多时的性能问题

如果你在业务代码里对大量路径注册了Watcher，要特别注意ZK的watch机制是有内存开销的。每注册一个Watcher，客户端和服务端都要维护对应的引用。当Watcher数量超过几万个时，客户端的内存会明显上涨，事件处理也会变慢。

我的建议是，不要让每个业务请求都动态注册Watcher，尽量把监听注册和业务逻辑解耦，使用公共路径的监听，或者用Curator的cache机制批量管理。比如在配置中心场景，所有配置项可以聚合到一个大路径下，监听父路径的NodeChildrenChanged事件，而不是对每个配置节点都注册Watcher。

5.3 原生API和Curator的生产选型经验

到这儿，原生API基本讲完了。生产环境我实际上大部分项目用的是Curator，原因不是原生API不好，而是Curator把很多生产必备的功能都封装好了。

对比一下：

特性	原生API	Curator
Watcher重注册	自己管理，容易漏	NodeCache/PathChildrenCache自动处理
递归创建/删除节点	需要自己写循环	creatingParentsIfNeeded / deletingChildrenIfNeeded
分布式锁	手写逻辑	InterProcessMutex
Leader选举	手写逻辑	LeaderSelector
重试策略	无	内置多种RetryPolicy
依赖复杂度	低	引入较多依赖

如果是简单的配置读取，原生API就够用。如果是分布式锁、Leader选举、服务发现这类高级场景，建议直接上Curator。

不过有一点要提醒：Curator 4.x版本对应ZK 3.5.x，Curator 5.x对应ZK 3.6.x。选版本时一定要先确认你连接的ZK集群版本，再做对应选择。我吃过一次亏，用的Curator 5.1和线上的ZK 3.4.6通信，老版本ZK不支持新协议的某些特性，客户端日志里一堆警告。

5.4 我在实际项目中的踩坑总结

最后分享几个只有实操才会遇到的细节问题，希望能帮你避开。

第一个坑是误用已关闭的ZooKeeper实例。我们的应用里ZK客户端是单例的，但有一次重构时，一段代码在应用关闭时调用了zk.close()，但另外一条线程还在用同一个实例创建节点，结果疯狂抛ConnectionClosedException。这个问题排查了很久，最后是加了一个zk.getState()判断：

if (zk.getState() == ZooKeeper.States.CLOSED) { // 重新初始化客户端 }

第二个坑是分布式锁忘记释放临时节点。我见过有同事写分布式锁，锁的业务逻辑抛异常后没有走finally块调用unlock()，导致节点一直存在，其他线程永远拿不到锁。后来我们在代码里强制要求lock和unlock必须配对出现，并且unlock放到finally块中。使用临时节点的好处是即使忘记删除，会话断开以后节点也会消失，但问题在于会话可能还连着，节点会一直占着。

第三个坑是getChildren的Watcher注册在回调里丢失。这里特别提醒一下，getChildren(path, watcher)虽然也能注册Watcher监听子节点变化，但这个Watcher同样是一次性的。你在回调里再次调用getChildren时需要重新传入Watcher，否则后续变化感知不到。这个逻辑我一开始没意识到，导致上线的配置动态更新功能过了一天就完全不生效了。

第四个坑是数据序列化问题。ZK存的是字节数组，如果直接用String.getBytes()存中文，取出来也要用相同字符集解码。项目里最好统一用UTF-8，并且把序列化和反序列化的逻辑封装在同一个工具类里，避免散落在各业务代码中出现Charset混乱。

我个人在实际操作中最深的体会是：ZK客户端代码本身不难，难的是对分布式协调模型的理解。你写的每一行节点操作，背后都对应着ZK集群内部的一次原子写入；你注册的每一个Watcher，都代表着客户端和服务端之间的一次约定。生产里的各种诡异故障，十有八九是没处理好会话、临时节点和Watcher这三者的边界。把这几个概念吃透，ZK的实战路基本上就通了。