本章定位：ZNode 是 ZooKeeper 数据模型的基本单元。理解 ZNode 的类型、属性和操作语义，是使用 ZooKeeper 的起点。

定义与作用

ZooKeeper 的数据模型类似一个分布式文件系统，采用树形层次命名空间。树中的每个节点称为 ZNode。与文件系统的关键区别在于：ZNode 既可以像目录一样拥有子节点，又可以像文件一样存储数据。

ZNode 解决的核心痛点：

核心原理

树形命名空间

图中 /app/config 存储持久配置数据，/app/services/ 下的子节点为 Ephemeral 类型（服务实例存活标识），/app/locks/ 下为带序号的临时节点。

ZNode 的核心属性

每个 ZNode 维护一个 Stat 结构，包含以下字段：

完整示例

示例一：基本 CRUD 操作

场景说明：模拟配置中心场景，创建、读取、更新和删除配置节点。

操作前状态：空 ZooKeeper 树。

zkCli.sh -server 127.0.0.1:2181

创建节点：

[zkshell: 0] create /app "application-root"
Created /app

[zkshell: 1] create /app/config "port=8080,debug=false"
Created /app/config

读取数据：

[zkshell: 2] get /app/config
port=8080,debug=false
cZxid = 0x2
ctime = Sat Jun 13 10:00:00 CST 2026
mZxid = 0x2
mtime = Sat Jun 13 10:00:00 CST 2026
pZxid = 0x2
cversion = 0
dataVersion = 0
aclVersion = 0
ephemeralOwner = 0x0
dataLength = 24
numChildren = 0

更新数据：

[zkshell: 3] set /app/config "port=9090,debug=true"
cZxid = 0x2
...
mZxid = 0x3          # 事务 ID 递增
dataVersion = 1      # 版本号从 0 → 1

[zkshell: 4] get /app/config
port=9090,debug=true

操作后状态：

版本号乐观锁演示：

# 使用旧版本号更新——失败
[zkshell: 5] set -v 0 /app/config "should fail"
version No is not valid : /app/config
# KeeperErrorCode = BadVersion

版本号机制保证了并发安全：客户端读到的 version=1，如果在此期间其他客户端已更新为 version=2，则使用 version=1 的 set 操作会失败。

示例二：ZNode 的 Stat 追踪

场景说明：通过 Java API 观察 ZNode 创建、修改全过程的版本变化。

import org.apache.zookeeper.*;
import org.apache.zookeeper.data.Stat;

public class ZNodeStatDemo {
    public static void main(String[] args) throws Exception {
        ZooKeeper zk = new ZooKeeper("127.0.0.1:2181", 3000, event -> {});

        // 1. 创建节点
        String path = zk.create("/stat-demo", "v1".getBytes(),
                ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode.PERSISTENT);
        System.out.println("Created: " + path);

        // 2. 获取 Stat
        Stat stat = new Stat();
        byte[] data = zk.getData("/stat-demo", false, stat);
        System.out.printf("version=%d, data=%s%n",
                stat.getVersion(), new String(data));

        // 3. 更新数据
        stat = zk.setData("/stat-demo", "v2".getBytes(), stat.getVersion());
        System.out.printf("After setData: version=%d%n", stat.getVersion());

        // 4. 创建子节点
        zk.create("/stat-demo/child", "child-data".getBytes(),
                ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode.PERSISTENT);

        // 5. 再次获取 Stat
        stat = zk.exists("/stat-demo", false);
        System.out.printf("cversion=%d, numChildren=%d%n",
                stat.getCversion(), stat.getNumChildren());

        zk.close();
    }
}

执行结果：

Created: /stat-demo
version=0, data=v1
After setData: version=1
cversion=1, numChildren=1

操作前后对比：

示例三：数据大小限制

场景说明：验证 ZNode 数据量上限（默认 1MB）。

# 尝试写入超过 1MB 的数据
[zkshell: 0] create /large_node "（此处为超过 1MB 的字符串）"
# KeeperErrorCode = MarshallingError

操作前状态：未超出限制的节点正常创建。

操作结果：超出 1MB 限制时，服务端直接拒绝，抛出 MarshallingError。

ZooKeeper 不是通用数据库，ZNode 设计目标存储的是协调元数据（配置、状态等），通常在 KB 级别。大数据应存储在 HDFS 等系统，ZooKeeper 中只存储指针。

易错场景与面试考点

易错场景

1. 空节点不等于不存在的节点

create /empty ""
# 创建成功，dataLength=0

get /empty
# 返回空字符串，但 Stat 有效

stat /not-exist
# KeeperErrorCode = NoNode

dataLength=0 和 NoNode 是两种完全不同的状态。前者是存在的空数据节点，后者是不存在的路径。

2. version 不是全局自增 ID

容易将 version 误解为"第几次修改"。实际上 version 表示该节点自身被修改的次数，不同节点的 version 值互相独立。

3. ZNode 路径约束

以下字符不可用于路径：

• \u0000（空字符）
• 控制字符 \u0001 ~ \u001F、\u007F ~ \u009F
• Unicode 代理区 \ud800 ~ \uF8FF、\uFFF0 ~ \uFFFF
• . 和 .. 不能作为独立路径段
• zookeeper 是保留关键字

面试高频题

Q：ZooKeeper 的数据模型与文件系统有何异同？

A：

• 相同点：树形结构、层次命名空间、路径访问（/a/b/c）
• 不同点：ZNode 可同时拥有数据和子节点（文件系统只能二选一）；ZNode 支持 Ephemeral/Sequential 等特殊类型；数据大小限制在 1MB 以内；不支持相对路径。

Q：version 字段有什么用？

A：version 是实现乐观锁的核心。每次 setData 前传入期望的 version，服务端校验一致才写入。这保证了在分布式环境下无需额外加锁即可实现原子 CAS 操作。

Q：ephemeralOwner 什么时候为 0？

A：持久节点（Persistent）的 ephemeralOwner 始终为 0。只有临时节点（Ephemeral）的 ephemeralOwner 才是创建它的 Session ID。

小结

ZNode 是后续所有机制的基础。下一节将深入不同类型的 ZNode（持久/临时/顺序）及其适用场景。