服务注册与分布式协调 / 系统课时
异步 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 与回调的分发。

用 DataCallback 接收结果
下面示例假设项目已经引入与服务端兼容的 org.apache.zookeeper:zookeeper 客户端依赖,并且本机 127.0.0.1:2181 有可连接的 ZooKeeper。程序先准备测试节点,再异步读取数据;RequestContext 用来携带调用链标识和起始时间。
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");
}
}
}
}预期输出:
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 往往更容易控制。选择关键不是“异步一定更快”,而是能否正确处理回调线程、错误码和不确定写结果。