服务注册与分布式协调 / 系统课时
同步 API 操作
同步 API 操作
本课使用 Java 原生同步 API 完成一次完整的 znode 生命周期。你将创建节点、读取数据和 Stat、按版本更新、删除节点,并通过明确输出验证每个操作是否成功。
学习目标
- 使用同步 API 创建、读取、更新和删除节点
- 从
Stat获取数据版本并用于条件写入 - 识别同步调用的阻塞特性和常见异常
同步 API 的执行方式
同步方法会阻塞当前线程,直到服务器返回结果或发生超时。它适合命令行工具、低并发管理任务和教学示例,但不应直接阻塞高并发业务线程。
本课复用上一课的 Maven 项目。示例使用开放 ACL,便于本地实验;生产环境应根据身份认证和权限模型配置 ACL。
完整 CRUD 示例
创建 src/main/java/com/example/SyncCrudDemo.java:
package com.example;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import org.apache.zookeeper.CreateMode;
import org.apache.zookeeper.Watcher;
import org.apache.zookeeper.ZooDefs;
import org.apache.zookeeper.ZooKeeper;
import org.apache.zookeeper.data.Stat;
public final class SyncCrudDemo {
private static final String PATH = "/course-sync-demo";
private SyncCrudDemo() {
}
public static void main(String[] args) throws Exception {
String connectString = args.length > 0
? args[0]
: "127.0.0.1:2181";
try (ZooKeeper zk = connect(connectString)) {
// 清理旧节点,使示例可以重复执行并保持版本结果稳定。
Stat old = zk.exists(PATH, false);
if (old != null) {
zk.delete(PATH, old.getVersion());
}
String createdPath = zk.create(
PATH,
"v1".getBytes(StandardCharsets.UTF_8),
ZooDefs.Ids.OPEN_ACL_UNSAFE,
CreateMode.PERSISTENT);
System.out.println("created=" + createdPath);
// getData 同时返回数据,并把当前版本写入 Stat。
Stat readStat = new Stat();
byte[] firstData = zk.getData(PATH, false, readStat);
System.out.printf(
"read=%s version=%d%n",
new String(firstData, StandardCharsets.UTF_8),
readStat.getVersion());
// 使用读取到的版本执行条件更新,防止覆盖并发写入。
Stat updatedStat = zk.setData(
PATH,
"v2".getBytes(StandardCharsets.UTF_8),
readStat.getVersion());
System.out.printf(
"updated=v2 version=%d%n",
updatedStat.getVersion());
zk.delete(PATH, updatedStat.getVersion());
System.out.println("deleted=" + (zk.exists(PATH, false) == null));
}
}
private static ZooKeeper connect(String connectString) throws Exception {
CountDownLatch connected = new CountDownLatch(1);
ZooKeeper zk = new ZooKeeper(
connectString,
10_000,
event -> {
if (event.getState()
== Watcher.Event.KeeperState.SyncConnected) {
connected.countDown();
}
});
// 连接等待必须有上限,超时后主动关闭客户端。
if (!connected.await(10, TimeUnit.SECONDS)) {
zk.close();
throw new IllegalStateException("连接 ZooKeeper 超时");
}
return zk;
}
}示例先清理同名旧节点,以保证重复运行时结果稳定。getData 把节点状态写入 Stat,随后 setData 使用读取到的版本执行条件更新。
运行与预期输出
执行:
mvn -q -Dexec.mainClass=com.example.SyncCrudDemo -Dexec.args="127.0.0.1:2181" exec:java预期输出:
created=/course-sync-demo
read=v1 version=0
updated=v2 version=1
deleted=true新建节点的数据版本通常从 0 开始,每次成功 setData 后递增。若其他客户端在读取和更新之间改过节点,本次更新会抛出 BadVersionException。
常见异常处理
NodeExistsException 表示创建路径已存在;NoNodeException 表示目标节点不存在;NotEmptyException 表示删除的节点仍有子节点;ConnectionLossException 表示客户端无法确认请求结果。
尤其要注意创建或删除遇到连接丢失时,服务器可能已经执行成功。业务代码不能简单无条件重试,应先查询当前状态,再决定补偿动作。
同步 API 的使用边界
同步调用代码直观,但每次网络等待都会占用线程。Web 服务中应设置独立线程池、超时和限流,或在高并发路径中使用异步 API 和更高层客户端框架。
不要使用版本 -1 作为默认更新策略。它会跳过版本检查,虽然方便,却可能覆盖其他客户端刚写入的数据。
本课总结
- 同步 API 按调用顺序返回结果,适合低并发和管理型任务
Stat中的版本应传给更新和删除操作,形成条件写入- 连接丢失时结果可能不确定,重试前要先查询服务器状态
下一课预告
下一课将把同样的操作改为异步调用,使用回调函数处理结果码、请求上下文和后续步骤。