SpringBoot升级后Zookeeper出现两类异常的排查求助

错误原因拆解 #

错误1：KeeperException$UnimplementedException #

这个异常本质是ZooKeeper客户端与服务端版本不兼容：你使用3.6.0的客户端，但如果服务端仍为旧版本（比如原有的3.4.12），客户端调用了服务端未实现的API（比如3.6新增的节点创建参数、特性），就会触发该错误。

错误2：ClassNotFoundException: org.apache.zookeeper.admin.ZooKeeperAdmin #

ZooKeeperAdmin是ZooKeeper 3.5+才新增的类，出现这个问题说明依赖中同时存在旧版（3.4.x）和新版（3.5+/3.6.x）的ZooKeeper jar包，或者Curator版本依赖了3.5+的ZooKeeper类，但实际引入的是3.4.x的客户端。

核心解决方案 #

1. 对齐ZooKeeper客户端与服务端版本 #

• 如果服务端无法升级（仍为3.4.12）：
  • 必须使用兼容3.4.x的Curator版本（Curator 4.x系列，比如4.3.0），同时客户端ZooKeeper版本保持与服务端一致或兼容的3.4.x版本（比如3.4.14）。
  • Curator与ZooKeeper官方兼容关系：
    • Curator 4.x → ZooKeeper 3.4.x / 3.5.x
    • Curator 5.x → ZooKeeper 3.6.x+

2. 强制统一依赖版本（以Maven为例） #

Spring Boot 2.7.4对应的Spring Cloud 2021.0.x默认引入Curator 5.1.0和ZooKeeper 3.6.0，需要在pom.xml中强制覆盖版本，避免依赖冲突：

<properties>
    <!-- 匹配服务端版本的ZooKeeper客户端 -->
    <zookeeper.version>3.4.14</zookeeper.version>
    <!-- 兼容3.4.x的Curator版本 -->
    <curator.version>4.3.0</curator.version>
</properties>

<dependencyManagement>
    <dependencies>
        <!-- 统一Curator所有模块版本 -->
        <dependency>
            <groupId>org.apache.curator</groupId>
            <artifactId>curator-framework</artifactId>
            <version>${curator.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.curator</groupId>
            <artifactId>curator-recipes</artifactId>
            <version>${curator.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.curator</groupId>
            <artifactId>curator-x-discovery</artifactId>
            <version>${curator.version}</version>
        </dependency>
        <!-- 统一ZooKeeper客户端版本，排除冲突日志依赖 -->
        <dependency>
            <groupId>org.apache.zookeeper</groupId>
            <artifactId>zookeeper</artifactId>
            <version>${zookeeper.version}</version>
            <exclusions>
                <exclusion>
                    <groupId>org.slf4j</groupId>
                    <artifactId>slf4j-log4j12</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
    </dependencies>
</dependencyManagement>

3. 排查依赖冲突 #

执行mvn dependency:tree命令，检查输出中是否有多个版本的zookeeper或curator-*依赖，找到并排除掉非预期的旧版本依赖。

4. Java版本无需升级 #

Spring Boot 2.7.4完全支持Java 8，你的问题与Java版本无关，无需升级。

额外检查点 #

• 确认服务端ZooKeeper的配置，是否开启了兼容旧客户端的模式（比如3.6服务端兼容3.4客户端的配置）。
• 检查服务注册代码中是否使用了ZooKeeper 3.6新增的API（比如CreateMode的新枚举、ACL的新设置），如果有，改为兼容3.4.x的实现。

内容的提问来源于stack exchange，提问作者Krish