服务注册与分布式协调 / 系统课时
常见错误码诊断
常见错误码诊断
本课解决 ZooKeeper 客户端出现 ConnectionLoss、OperationTimeout、NoNode、BadVersion 等错误时不知道是否重试的问题。你将按“结果是否确定”和“前置条件是否变化”选择查询、重试或业务补偿。
学习目标
- 理解常见错误码代表的故障层次
- 判断写操作失败后结果是否已经生效
- 为不同错误设计重试、幂等和补偿策略
先按结果确定性分类
| 错误码 | 典型含义 | 结果是否确定 | 推荐处理 |
|---|---|---|---|
| ConnectionLoss | 请求过程中连接中断 | 写操作可能已提交 | 重连后查询状态,再决定补偿 |
| OperationTimeout | 客户端等待超过期限 | 可能仍在服务端处理中 | 查询确认,避免盲目重复写 |
| NoNode | 目标节点不存在 | 通常可确定前置条件不成立 | 检查路径、初始化顺序或并发删除 |
| NodeExists | 创建目标已存在 | 当前创建未按预期完成 | 校验现有数据是否属于同一业务 |
| BadVersion | 版本号不匹配 | 条件更新未执行 | 重新读取并做冲突处理 |
| SessionExpired | 旧会话已经失效 | 会话态资源不可继续信任 | 建立新会话并重建资源 |
ConnectionLoss 和 OperationTimeout 最危险,因为客户端“不知道结果”,不等于服务端“没有执行”。对 create、setData、multi 等写操作直接重试,可能产生重复节点、覆盖新值或重复业务动作。
建立统一决策器
下面是片段示例,依赖 ZooKeeper Java 客户端的 KeeperException.Code。它只表达错误分类,实际项目还要结合操作类型、幂等键和重试次数。
import org.apache.zookeeper.KeeperException;
enum RetryDecision {
QUERY_THEN_DECIDE,
RETRY_AFTER_REFRESH,
FAIL_FAST,
REBUILD_SESSION
}
static RetryDecision classify(int rc) {
KeeperException.Code code = KeeperException.Code.get(rc);
return switch (code) {
case CONNECTIONLOSS, OPERATIONTIMEOUT ->
RetryDecision.QUERY_THEN_DECIDE;
case BADVERSION ->
RetryDecision.RETRY_AFTER_REFRESH;
case SESSIONEXPIRED ->
RetryDecision.REBUILD_SESSION;
case NONODE, NODEEXISTS, NOAUTH, AUTHFAILED ->
RetryDecision.FAIL_FAST;
default ->
RetryDecision.FAIL_FAST;
};
}预期行为
CONNECTIONLOSS -> QUERY_THEN_DECIDE
BADVERSION -> RETRY_AFTER_REFRESH
SESSIONEXPIRED -> REBUILD_SESSION
NONODE -> FAIL_FASTNoNode 和 NodeExists 是否真正失败仍取决于业务语义。例如幂等创建固定路径时,NodeExists 可能表示前一次请求已经成功,此时应读取并比对节点数据,而不是直接报错。
处理不确定写入
为每次业务写入设计可查询的唯一标识。创建任务节点可把业务请求 ID 放进节点名或数据中;连接丢失后先检查该标识是否存在,再决定是否重试。
顺序节点更难通过返回路径确认结果。可在节点数据中写入唯一请求 ID,重连后扫描限定范围并匹配;扫描范围必须受控,不能每次遍历超大目录。
处理版本冲突
BadVersion 是乐观并发控制生效的正常结果,不应无条件循环重试。客户端应重新读取数据和 Stat.version,判断新值是否仍适用,再使用新版本提交。
若更新具有覆盖风险,应把冲突返回业务层;若更新可交换或可合并,才适合在限定次数内重新计算后重试。重试必须带退避和上限,避免竞争激烈时形成活锁。
处理会话失效
SessionExpired 表示旧会话无法恢复。旧会话创建的临时节点已经或即将被服务端删除,旧 Watch 也不能继续依赖。客户端需要创建新会话,并重新注册服务、选举候选、锁和监听。
ConnectionLoss 期间不要立即假定临时节点已消失;只有确认连接状态进入 LOST 或收到 SessionExpired 后,才按新会话流程重建资源。
诊断记录与验证
每条错误日志至少记录操作类型、路径、错误码、会话 ID、请求 ID、重试次数和耗时。不要记录敏感节点内容,也不要只输出异常堆栈而缺少业务上下文。
故障演练时分别注入短暂断网、会话超时和并发版本冲突,验证不确定写入先查询、版本冲突不会无限重试、会话失效后旧锁和旧选举资格不再被使用。
本课总结
ConnectionLoss和OperationTimeout代表结果不确定,不能直接等同于失败NoNode、NodeExists和BadVersion要结合业务前置条件处理SessionExpired必须创建新会话并重建临时节点、选举和监听状态
下一课预告
下一课进入生产级综合实践,先把服务注册、配置监听、主节点选举和任务互斥整合为一个可验收的项目架构。