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

异步 API 与回调

异步 API 与回调

ZooKeeper 异步 API 让调用线程不必等待网络往返,但结果不会直接作为返回值交付,而是由客户端事件线程在稍后执行回调。本节用一个完整 Java 示例串起 rc 错误码、ctx 上下文和回调线程边界。

学习目标

  • 调用 ZooKeeper 原生异步接口并正确读取回调中的结果数据。
  • 使用 KeeperException.Code 处理 OK、NONODE、CONNECTIONLOSS 等结果。
  • 理解 ctx 只在客户端内部传递,以及回调中不能执行长时间阻塞任务的原因。

异步调用把结果移交给回调

以 getData 为例,同步重载会阻塞当前线程并直接返回数据;异步重载在提交请求后立即返回 void,服务端结果随后由 DataCallback 接收。回调参数中的 rc 是结果码,path 是请求路径,ctx 是调用方原样附带的客户端对象,data 和 stat 只在相应结果可用时读取。

ZooKeeper Java 客户端内部由发送线程维护网络通信,再由事件线程分发 Watcher 事件和异步回调。也就是说,“异步”并不等于“每个回调自动获得一个业务线程”;如果回调里直接做慢 SQL、HTTP 或大计算,会拖慢后续 Watcher 与回调的分发。

ZooKeeper 异步 API 回调时序

用 DataCallback 接收结果

下面示例假设项目已经引入与服务端兼容的 org.apache.zookeeper:zookeeper 客户端依赖,并且本机 127.0.0.1:2181 有可连接的 ZooKeeper。程序先准备测试节点,再异步读取数据;RequestContext 用来携带调用链标识和起始时间。

java
import org.apache.zookeeper.CreateMode;
import org.apache.zookeeper.KeeperException;
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.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;

public class AsyncGetDataDemo {
    private static final String CONNECT = "127.0.0.1:2181";
    private static final String PATH = "/anystack-async";

    static final class RequestContext {
        final String requestId;
        final long startedNanos;

        RequestContext(String requestId, long startedNanos) {
            this.requestId = requestId;
            this.startedNanos = startedNanos;
        }
    }

    public static void main(String[] args) throws Exception {
        CountDownLatch connected = new CountDownLatch(1);
        CountDownLatch callbackDone = new CountDownLatch(1);

        try (ZooKeeper zk = new ZooKeeper(CONNECT, 10_000, event -> {
            if (event.getState() == Watcher.Event.KeeperState.SyncConnected) {
                connected.countDown();
            }
        })) {
            if (!connected.await(5, TimeUnit.SECONDS)) {
                throw new IllegalStateException("ZooKeeper connection timeout");
            }

            // 只用于构造稳定的演示数据,核心读取仍使用异步 API。
            Stat current = zk.exists(PATH, false);
            byte[] value = "hello".getBytes(StandardCharsets.UTF_8);
            if (current == null) {
                zk.create(PATH, value, ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode.PERSISTENT);
            } else {
                zk.setData(PATH, value, -1);
            }

            RequestContext ctx = new RequestContext("req-001", System.nanoTime());

            zk.getData(PATH, false, (rc, path, callbackCtx, data, stat) -> {
                try {
                    KeeperException.Code code = KeeperException.Code.get(rc);
                    RequestContext requestCtx = (RequestContext) callbackCtx;

                    if (code == KeeperException.Code.OK) {
                        long elapsedMs =
                                TimeUnit.NANOSECONDS.toMillis(System.nanoTime() - requestCtx.startedNanos);
                        System.out.printf(
                                "code=%s path=%s ctx=%s data=%s version=%d elapsedMs=%d%n",
                                code, path, requestCtx.requestId,
                                new String(data, StandardCharsets.UTF_8),
                                stat.getVersion(), elapsedMs);
                    } else {
                        System.out.printf(
                                "code=%s path=%s ctx=%s%n",
                                code, path, requestCtx.requestId);
                    }
                } finally {
                    // 回调必须尽快结束,避免阻塞 ZooKeeper EventThread。
                    callbackDone.countDown();
                }
            }, ctx);

            if (!callbackDone.await(5, TimeUnit.SECONDS)) {
                throw new IllegalStateException("Async callback timeout");
            }
        }
    }
}

预期输出:

text
code=OK path=/anystack-async ctx=req-001 data=hello version=<VALUE> elapsedMs=<VALUE>

version 会随重复执行而变化,elapsedMs 取决于本机和网络环境,因此使用动态占位。示例中的同步 exists、create 和 setData 只是准备数据,不影响对异步 getData 回调机制的观察。

错误码决定后续动作

异步调用提交成功后,服务端结果主要通过 rc 进入回调,而不是像同步 API 那样把 KeeperException 直接抛回调用点。推荐先把 rc 转成 KeeperException.Code,再按语义分支,避免把所有非零结果都当成同一种“网络失败”。

结果码 含义 常见处理
OK 请求成功 读取 data、stat 或对应返回值
NONODE 目标 znode 不存在 按业务判断创建、忽略或返回缺失,不盲目重试
CONNECTIONLOSS 请求期间连接丢失 读请求通常可重试;写请求先判断结果是否可能已经提交
SESSIONEXPIRED 会话已过期 不能继续复用旧会话,应重建客户端并恢复业务状态

对写操作尤其要注意 CONNECTIONLOSS:客户端没收到确认并不等于服务端一定没执行。若直接重复 create、setData 或顺序节点创建,可能得到重复副作用或与预期不同的版本,因此应结合幂等设计、节点状态检查或更高层业务标识确认结果。

ctx 只用于客户端关联

ctx 不会被序列化发送给 ZooKeeper 服务端,它只是客户端把一次请求与后续回调重新关联起来的对象。适合放请求 ID、调用开始时间、业务键或轻量追踪信息,不适合塞入大对象,更不能把它当成服务端会保存的元数据。

由于回调运行在客户端事件分发线程,回调内应完成“判断结果、提取必要数据、投递后续任务”后尽快返回。真正耗时的数据库访问、远程 HTTP 调用或 CPU 计算应交给应用自己的线程池,否则一个慢回调就可能拖住同一客户端上的其他异步结果和 Watcher 事件。

当请求量高、单次操作相互独立,或者应用本来就采用事件驱动模型时,异步 API 能减少等待线程数量;当流程很短、依赖前一步立即返回值且并发不高时,同步 API 往往更容易控制。选择关键不是“异步一定更快”,而是能否正确处理回调线程、错误码和不确定写结果。

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

目录与阅读设置

阅读设置

17

记录一个想法

异步 API 与回调

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

登录哪都通