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

创建 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;生产项目应根据服务端版本和官方兼容说明统一依赖版本。

xml
<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 和依赖是否有效:

bash
mvn -q compile

预期结果:

text
命令正常结束且退出码为 0;首次执行可能显示依赖下载日志。

创建连接代码

在 src/main/java/com/example/ConnectDemo.java 中写入:

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 正常运行,然后执行:

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

预期输出的关键部分:

text
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 完成节点的创建、读取、版本化更新和删除,并处理每一步的返回结果。

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

目录与阅读设置

阅读设置

17

记录一个想法

创建 Java 客户端项目

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

登录哪都通