ZooKeeper 常被用于服务发现、主节点选举、分布式锁和配置协调。初次接触 Java API 时，开发者通常会把注意力放在 create、getData 和 delete 这几个方法上，但生产问题往往不在方法签名，而在操作前后的约束：父节点是否存在、节点是否由当前会话持有、数据是否已被其他客户端修改、连接是否真的可用，以及重试会不会产生重复结果。
例如，两个实例同时读取 /demo/config，随后都基于旧值更新。若更新时直接使用版本 -1，后提交的实例会覆盖先提交的结果；若删除节点时也忽略版本，则可能删掉读取之后已经被别人更新的数据。单机文件操作中不明显的问题，在分布式环境里会直接演变为竞态条件。
本文不依赖业务框架，使用 ZooKeeper 原生 Java 客户端构建一个最小但完整的节点管理示例。重点不是封装更多方法，而是明确每项操作的语义和失败边界。
先理解 ZooKeeper 的数据模型
ZooKeeper 将数据组织为类似文件系统的树。树中的每个节点称为 znode，一个 znode 同时包含路径、字节数据和元信息。它不是通用文件存储，节点数据应保持精简；具体大小限制和运维阈值应以所部署版本的官方文档及集群配置为准。
创建节点时需要选择模式：
PERSISTENT：持久节点，不会因为创建者会话结束而自动删除。EPHEMERAL：临时节点，所属会话失效后由服务端清理，常用于实例注册和存活标记。PERSISTENT_SEQUENTIAL：持久顺序节点，服务端在给定路径后附加单调递增序号。EPHEMERAL_SEQUENTIAL：临时顺序节点，常用于选举或锁队列。
每个 znode 都有数据版本 version。成功调用 setData 后，版本会变化。客户端可以把读取时得到的版本带回更新或删除请求，实现乐观并发控制。传入 -1 表示不检查版本，虽然方便，却会主动放弃冲突检测。
ZooKeeper 的 Watch 是一次性变化通知，不是永久订阅。客户端收到事件后，如果还要继续观察，必须重新注册 Watch；通知只说明状态可能改变，业务逻辑仍应再次读取数据，而不能把通知本身当作完整状态。
准备本地环境
下面用容器启动单节点环境，仅用于开发和接口验证。镜像标签通过环境变量显式指定，避免示例暗中假定某个版本。实际项目应根据服务器版本、Java 客户端兼容范围和组织的镜像策略选择标签。
创建 compose.yaml：
services:
zk:
image: ${
ZOOKEEPER_IMAGE:?set ZOOKEEPER_IMAGE first}
hostname: zk
ports:
- "2181:2181"
environment:
ZOO_MY_ID: "1"
ZOO_STANDALONE_ENABLED: "true"
restart: unless-stopped
启动前设置镜像并检查服务状态：
export ZOOKEEPER_IMAGE='zookeeper:<经过验证的标签>'
docker compose up -d
docker compose ps
单节点部署不具备集群容错能力，不能据此推导生产集群的可用性、吞吐量或故障恢复表现。
Maven 项目中引入客户端依赖。版本应由项目统一管理，并与目标集群做兼容性验证：
<properties>
<zookeeper.version>在此填写已验证版本</zookeeper.version>
</properties>
<dependencies>
<dependency>
<groupId>org.apache.zookeeper</groupId>
<artifactId>zookeeper</artifactId>
<version>${zookeeper.version}</version>
</dependency>
</dependencies>
连接地址不要硬编码到业务类中。运行时从环境变量读取：
export ZK_CONNECT='127.0.0.1:2181'
实现可控的 Java 客户端
构造 ZooKeeper 对象并不等于连接已经建立。连接过程是异步的，因此示例使用 CountDownLatch 等待 SyncConnected。等待必须有上限，不能让应用启动过程永久阻塞。
package example;
import org.apache.zookeeper.CreateMode;
import org.apache.zookeeper.KeeperException;
import org.apache.zookeeper.WatchedEvent;
import org.apache.zookeeper.Watcher;
import org.apache.zookeeper.ZooDefs;
import org.apache.zookeeper.ZooKeeper;
import org.apache.zookeeper.data.Stat;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
public final class ZkNodeManager implements AutoCloseable {
private final ZooKeeper client;
private ZkNodeManager(ZooKeeper client) {
this.client = client;
}
public static ZkNodeManager connect(
String connectString,
Duration sessionTimeout,
Duration connectTimeout) throws Exception {
CountDownLatch connected = new CountDownLatch(1);
ZooKeeper zk = new ZooKeeper(
connectString,
Math.toIntExact(sessionTimeout.toMillis()),
event -> {
if (event.getState() == Watcher.Event.KeeperState.SyncConnected) {
connected.countDown();
}
});
if (!connected.await(connectTimeout.toMillis(), TimeUnit.MILLISECONDS)) {
zk.close();
throw new IllegalStateException("ZooKeeper connection timed out");
}
return new ZkNodeManager(zk);
}
public void ensurePersistentPath(String path) throws Exception {
validateAbsolutePath(path);
if ("/".equals(path)) {
return;
}
String[] segments = path.substring(1).split("/");
String current = "";
for (String segment : segments) {
current += "/" + segment;
try {
client.create(
current,
new byte[0],
ZooDefs.Ids.OPEN_ACL_UNSAFE,
CreateMode.PERSISTENT);
} catch (KeeperException.NodeExistsException ignored) {
// 并发创建成功也满足“路径存在”的目标。
}
}
}
public Stat putIfVersion(String path, String value, int expectedVersion)
throws Exception {
byte[] bytes = value.getBytes(StandardCharsets.UTF_8);
return client.setData(path, bytes, expectedVersion);
}
public NodeValue read(String path) throws Exception {
Stat stat = new Stat();
byte[] data = client.getData(path, false, stat);
return new NodeValue(
new String(data, StandardCharsets.UTF_8),
stat.getVersion());
}
public boolean deleteIfVersion(String path, int expectedVersion)
throws Exception {
try {
client.delete(path, expectedVersion);
return true;
} catch (KeeperException.NoNodeException ignored) {
return false;
}
}
public List<String> children(String path) throws Exception {
return new ArrayList<>(client.getChildren(path, false));
}
private static void validateAbsolutePath(String path) {
if (path == null || !path.startsWith("/") || path.contains("//")) {
throw new IllegalArgumentException("Invalid absolute path: " + path);
}
}
@Override
public void close() throws InterruptedException {
client.close();
}
public record NodeValue(String value, int version) {
}
}
OPEN_ACL_UNSAFE 允许任何已连接且可访问集群的客户端操作节点，只适合隔离的本地实验。生产环境应根据认证方案设置 ACL，并分别授予读取、写入、创建、删除和管理权限。认证方式依赖实际部署，不能仅靠替换一行常量完成安全加固。
执行创建、更新和安全删除
下面的程序先建立父路径，再创建配置节点。创建请求捕获 NodeExistsException，使重复执行不会因为节点已经存在而中断。之后读取当前版本，使用该版本更新和删除。
package example;
import org.apache.zookeeper.CreateMode;
import org.apache.zookeeper.KeeperException;
import org.apache.zookeeper.ZooDefs;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
public final class Demo {
public static void main(String[] args) throws Exception {
String connect = System.getenv("ZK_CONNECT");
if (connect == null || connect.isBlank()) {
throw new IllegalStateException("ZK_CONNECT is required");
}
try (ZkNodeManager manager = ZkNodeManager.connect(
connect, Duration.ofSeconds(15), Duration.ofSeconds(5))) {
manager.ensurePersistentPath("/demo/config");
// ensurePersistentPath 创建的是空节点，先读取版本再更新。
ZkNodeManager.NodeValue initial = manager.read("/demo/config");
manager.putIfVersion(
"/demo/config", "feature.enabled=false", initial.version());
ZkNodeManager.NodeValue current = manager.read("/demo/config");
System.out.printf("value=%s, version=%d%n",
current.value(), current.version());
manager.putIfVersion(
"/demo/config", "feature.enabled=true", current.version());
ZkNodeManager.NodeValue latest = manager.read("/demo/config");
boolean deleted = manager.deleteIfVersion(
"/demo/config", latest.version());
System.out.println("deleted=" + deleted);
} catch (KeeperException.BadVersionException e) {
System.err.println("数据已被其他客户端修改，请重新读取后再决定是否重试");
}
}
}
编译和运行方式取决于项目采用的 Maven 插件。至少应先执行：
mvn test
mvn package
若使用 IDE，直接运行 Demo.main 即可。命令行启动时应使用项目生成的完整运行时 classpath；普通 JAR 默认不会自动包含依赖，不能只凭 java -jar 假定客户端依赖已经打包。
为什么不能无条件自动重试
连接抖动时，客户端可能得到 ConnectionLossException。此时请求是否已被服务端执行，不能仅凭客户端异常确定。对“确保某个持久路径存在”这种目标，重新检查路径通常可以恢复；但对创建顺序节点而言，直接重试可能生成第二个节点。更稳妥的做法是在节点数据或路径设计中加入请求标识，再通过查询确认前一次结果。
BadVersionException 也不应该被循环吞掉。它代表调用者依据的状态已经过期。正确处理通常是重新读取数据，根据最新值重新计算，并设置有限重试次数；涉及配置覆盖、主节点切换等高影响操作时，还应把冲突上报给业务层，而不是由基础组件擅自决定新值。
删除还有一个额外约束：存在子节点的 znode 不能直接删除。若确实需要递归删除，应先限定允许操作的路径前缀，列举子节点并从叶子向上删除，同时处理并发新增。不要提供对任意输入路径执行递归删除的公共接口，否则一次路径传递错误就可能扩大影响范围。
临时节点与会话失效
临时节点绑定的是 ZooKeeper 会话，不是某个 Java 对象的内存生命周期。短暂断网期间，只要服务端尚未判定会话过期，临时节点可能仍然存在；一旦会话过期，旧会话创建的临时节点会被清理。客户端重新连接并获得新会话后，应重新注册自身的临时节点。
因此，服务注册逻辑至少要区分以下状态：
Disconnected：连接暂时中断，先停止依赖强一致协调结果的操作，但不要立即假定临时节点已删除。Expired：会话已经失效，旧会话不能恢复，需要创建新客户端并重建临时节点及 Watch。SyncConnected：连接可用，但业务仍可能需要核对注册节点和本地状态。
具体状态回调和重连行为可能受客户端版本及封装库影响，应针对项目锁定的版本编写集成测试。
常见问题
为什么创建 /a/b 会提示父节点不存在？
ZooKeeper 的 create 不会自动递归创建父路径。应先创建 /a，再创建 /a/b。本文的 ensurePersistentPath 按层创建，并把并发导致的“已存在”视为成功。
为什么删除节点时报节点非空？
目标节点下面还有子节点。先调用 getChildren 核对内容，再按业务规则处理。递归删除不是天然安全的默认行为。
可以一直传 -1 作为版本吗？
只有在业务明确接受覆盖任意版本时才适合。配置更新、所有权变更和删除操作通常应携带读取到的版本，让并发冲突显式暴露。
Watch 为什么只触发一次？
这是其基本语义。收到通知后重新读取状态，并在读取时再次注册 Watch。还要考虑通知与重新注册之间发生变化的情况，因此最终判断必须依据服务端当前数据。
本地能连接，远程应用为什么超时？
依次检查连接串、端口监听地址、容器端口映射、防火墙、DNS、网络访问控制和服务端日志。若使用集群，还要确认客户端能够访问连接过程中获知的各服务端地址，而不只是最初填写的单个入口。
是否应该自己封装所有重试和 Watch？
不一定。原生 API 适合理解语义和实现小范围功能；复杂选举、锁、缓存与重连可以评估成熟客户端库。但引入封装并不会消除会话失效、幂等和权限设计，仍需验证其重试策略是否符合业务要求。
总结
ZooKeeper 节点管理的核心不是“把 CRUD 调通”，而是把状态变化放进会话和并发语义中处理。创建操作要考虑父路径和重复执行，更新与删除应利用版本号检测冲突，临时节点必须随会话重建，Watch 则要按一次性通知设计重新注册流程。
落地时可以遵循一条简单边界：先读取并保存版本，再执行有条件写入；遇到连接异常先核对结果，遇到版本冲突回到业务层重新决策。加上受限 ACL、明确的连接超时和针对会话失效的集成测试，节点操作才能从演示代码变成可维护的分布式协调组件。
