服务注册与分布式协调 / 系统课时
创建 Java 客户端项目
创建 Java 客户端项目
本课从零创建一个可运行的 Java 客户端。你将添加 Maven 依赖,建立异步连接,用 CountDownLatch 等待 SyncConnected,并输出真实会话 ID,避免连接尚未完成就开始调用 API。
学习目标
- 创建包含 ZooKeeper 客户端依赖的 Maven 项目
- 理解
new ZooKeeper()返回不代表连接已经可用 - 等待
SyncConnected后再执行后续操作
配置 Maven 项目
创建目录 src/main/java/com/example,并在项目根目录保存以下 pom.xml。示例使用 Java 17 和 ZooKeeper 3.9.2;生产项目应根据服务端版本和官方兼容说明统一依赖版本。
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>zookeeper-native-client</artifactId>
<version>1.0.0</version>
<!-- 统一编译版本,避免本机 JDK 默认值影响构建 -->
<properties>
<maven.compiler.release>17</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<zookeeper.version>3.9.2</zookeeper.version>
</properties>
<!-- 引入 ZooKeeper 原生客户端 -->
<dependencies>
<dependency>
<groupId>org.apache.zookeeper</groupId>
<artifactId>zookeeper</artifactId>
<version>${zookeeper.version}</version>
</dependency>
</dependencies>
<!-- exec 插件用于从 Maven 直接运行 main 方法 -->
<build>
<plugins>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>3.3.0</version>
</plugin>
</plugins>
</build>
</project>该配置会引入原生客户端和运行时依赖。若企业项目统一管理依赖版本,应把版本移到父 POM,而不是在多个模块重复声明。先执行编译命令验证 POM 和依赖是否有效:
mvn -q compile预期结果:
命令正常结束且退出码为 0;首次执行可能显示依赖下载日志。创建连接代码
在 src/main/java/com/example/ConnectDemo.java 中写入:
package com.example;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import org.apache.zookeeper.WatchedEvent;
import org.apache.zookeeper.Watcher;
import org.apache.zookeeper.ZooKeeper;
public final class ConnectDemo {
private ConnectDemo() {
}
public static void main(String[] args) throws Exception {
String connectString = args.length > 0
? args[0]
: "127.0.0.1:2181";
CountDownLatch connected = new CountDownLatch(1);
// 构造方法只启动异步连接,不能据此判断会话已可用。
try (ZooKeeper zooKeeper = new ZooKeeper(
connectString,
10_000,
event -> handleEvent(event, connected))) {
// 设置等待上限,避免服务不可达时主线程永久阻塞。
boolean ready = connected.await(10, TimeUnit.SECONDS);
if (!ready) {
throw new IllegalStateException("等待 SyncConnected 超时");
}
String sessionId = Long.toHexString(zooKeeper.getSessionId());
System.out.println("sessionId=0x" + sessionId);
}
}
private static void handleEvent(
WatchedEvent event,
CountDownLatch connected) {
System.out.printf(
"state=%s,type=%s%n",
event.getState(),
event.getType());
if (event.getState() == Watcher.Event.KeeperState.SyncConnected) {
// 只有收到 SyncConnected 才放行后续 API 调用。
connected.countDown();
}
}
}构造方法会立即启动后台连接线程,因此必须由 Watcher 通知连接完成。仅判断 ZooKeeper 对象不为空,不能证明会话已经建立。
运行与验证
确保本机或连接串中的 ZooKeeper 正常运行,然后执行:
mvn -q -Dexec.mainClass=com.example.ConnectDemo -Dexec.args="127.0.0.1:2181" exec:java预期输出的关键部分:
state=SyncConnected,type=None
sessionId=0x<SESSION_ID><SESSION_ID> 每次会话可能不同。若只出现 Disconnected 或最终超时,应检查连接串、2181 端口、防火墙和服务端状态。
连接参数边界
连接串可以包含多个地址,例如 zk1:2181,zk2:2181,zk3:2181。客户端会选择可用服务器,并在连接断开时尝试切换,但这些地址必须属于同一个 ZooKeeper 集群。
会话超时不是普通网络连接超时。客户端和服务端会协商有效值;短暂断线只会进入 Disconnected,超过会话超时才会进入 Expired,届时必须创建新的客户端对象。
本课总结
new ZooKeeper()建立的是异步连接,返回时不保证已经可用- 应监听
SyncConnected并设置等待上限,避免主线程无限阻塞 - 连接串应包含多个集群地址,以支持服务器切换
下一课预告
下一课将使用同步 API 完成节点的创建、读取、版本化更新和删除,并处理每一步的返回结果。