第三章 客户端出庭：API、会话与工具箱

第三章 客户端出庭：API、会话与工具箱

章节摘要：本章解决"代码怎么写"的问题：三种主流客户端各自的定位与取舍，原生 API 的会话模型与异步事件机制，以及 Curator 如何把重试、监听缓存、锁这些脏活打包成组件。读完你能为项目选对客户端，并写出连接稳定的第一版代码。

一条主线

法庭已经开张（第二章），本章你以当事人身份出场。主线跟着一段会话的生命周期走：一个客户端进程启动，与集群建立会话，完成若干读写，中途经历一次网络抖动与会话迁移，最后正常退出。这条线上的每个环节，不同的客户端给出的支持程度截然不同——原生 API 要求你亲自处理"会话失效后重建一切"的琐碎，ZkClient 帮你封装了重连，Curator 则更进一步把常用协作模式做成开箱即用的配方。

所以本章的选型问题，本质上是"你愿意为省心付多少依赖成本"。这个问题没有标准答案，只有场景匹配：一次性脚本用原生客户端无妨，长驻服务强烈建议 Curator，维护历史代码则要学会与 ZkClient 共处。三个节正好对应三种态度。

沿途站点

第一站，3.1 节 客户端选型。把三种客户端放上同一张对比台：原生 API 是协议的直接投影，透明但繁琐；ZkClient 补了重连与监听订阅，轻量但多年未大改；Curator 是官方盖章的进阶框架，重试策略、连接状态、Recipes 组件一应俱全，代价是多一层抽象与依赖。选型决策树在这里。

第二站，3.2 节 原生 API 实战。绕不开的地基课：会话如何建立、事件回调在哪个线程触发、Watcher 一次性触发为何是新手坟场。哪怕项目里永远用 Curator，看懂这一节才能在异常现场读懂栈帧与日志。

第三站，3.3 节 Curator 实战。日常生产力工具：会话与重试的声明式配置、NodeCache 与 TreeCache 的持续监听、增删改查的流式接口。第五章所有判例的代码都以 Curator 书写，这一节是它们的公共前置。

拐点与结论

本章最重要的转折点是 3.2 节的那个反直觉设计：Watcher 注册一次只生效一次。很多人把它当成缺陷，其实它是一致性设计的必然——服务端只为"触发那一刻"负责，触发之后你的监听器与新状态之间没有契约，若继续保留反而诱导你基于过时认知行动。理解这一点，Curator 的 NodeCache 为什么要"自动重新注册"就不再神秘：它是在应用层替你补回连续监听的体验，同时保证每次读到的都是注册后的新值。

读完本章你应该能：根据项目形态选择客户端并说明理由；用原生 API 完成会话建立、异步读写与事件注册；解释会话迁移时客户端无感知的原因；用 Curator 完成增删改查与两类缓存监听；说出重试策略的参数含义与选取逻辑。

下一章的接力

你会用客户端了，但每次写入时法庭内部发生了什么，依然是个黑盒。第四章打开它：ZAB 协议如何让一张提案全票通过，Leader 倒下后选主如何重启，Watcher 与会话在服务端又是什么形状。带着本章的客户端视角读第四章，你会不断发出"原来我那句 set 之后就发生了这个"的感叹——这正是把机制学活的方式。

本章结构速览

三个客户端的关系与学习顺序一图收拢：原生是地基，封装是效率，选型在两者之间找平衡：

学客户端有一层容易被忽略的收益：它是理解服务端的旁路。原生 API 的每个方法与服务端的一条处理路径一一对应，异常类型与服务端的拒绝原因一一对应——你在客户端栈帧里看到的 KeeperException 家族，翻到第四章都能找到对应的机制裁决。所以哪怕最终的生产代码全用 Curator，3.2 节的原生课也不建议跳过：它让你在框架之下仍有第一视角。

本章代码全部可以在第二章的单机沙盘上直接运行。建议的练习节奏：每读完一节，把示例代码敲一遍并故意制造一次故障（杀掉服务端、断网十秒、改错路径），观察异常的形状。客户端层的功夫三分在写、七分在坏情况下它还稳不稳。