服务注册与分布式协调 / 系统课时

同步 API 操作

同步 API 操作

本课使用 Java 原生同步 API 完成一次完整的 znode 生命周期。你将创建节点、读取数据和 Stat、按版本更新、删除节点,并通过明确输出验证每个操作是否成功。

学习目标

  • 使用同步 API 创建、读取、更新和删除节点
  • 从 Stat 获取数据版本并用于条件写入
  • 识别同步调用的阻塞特性和常见异常

同步 API 的执行方式

同步方法会阻塞当前线程,直到服务器返回结果或发生超时。它适合命令行工具、低并发管理任务和教学示例,但不应直接阻塞高并发业务线程。

本课复用上一课的 Maven 项目。示例使用开放 ACL,便于本地实验;生产环境应根据身份认证和权限模型配置 ACL。

完整 CRUD 示例

创建 src/main/java/com/example/SyncCrudDemo.java:

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 使用读取到的版本执行条件更新。

运行与预期输出

执行:

bash
mvn -q -Dexec.mainClass=com.example.SyncCrudDemo -Dexec.args="127.0.0.1:2181" exec:java

预期输出:

text
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 中的版本应传给更新和删除操作,形成条件写入
  • 连接丢失时结果可能不确定,重试前要先查询服务器状态

下一课预告

下一课将把同样的操作改为异步调用,使用回调函数处理结果码、请求上下文和后续步骤。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

同步 API 操作

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通