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

常见错误码诊断

常见错误码诊断

本课解决 ZooKeeper 客户端出现 ConnectionLoss、OperationTimeout、NoNode、BadVersion 等错误时不知道是否重试的问题。你将按“结果是否确定”和“前置条件是否变化”选择查询、重试或业务补偿。

学习目标

  • 理解常见错误码代表的故障层次
  • 判断写操作失败后结果是否已经生效
  • 为不同错误设计重试、幂等和补偿策略

先按结果确定性分类

错误码 典型含义 结果是否确定 推荐处理
ConnectionLoss 请求过程中连接中断 写操作可能已提交 重连后查询状态,再决定补偿
OperationTimeout 客户端等待超过期限 可能仍在服务端处理中 查询确认,避免盲目重复写
NoNode 目标节点不存在 通常可确定前置条件不成立 检查路径、初始化顺序或并发删除
NodeExists 创建目标已存在 当前创建未按预期完成 校验现有数据是否属于同一业务
BadVersion 版本号不匹配 条件更新未执行 重新读取并做冲突处理
SessionExpired 旧会话已经失效 会话态资源不可继续信任 建立新会话并重建资源

ConnectionLoss 和 OperationTimeout 最危险,因为客户端“不知道结果”,不等于服务端“没有执行”。对 create、setData、multi 等写操作直接重试,可能产生重复节点、覆盖新值或重复业务动作。

建立统一决策器

下面是片段示例,依赖 ZooKeeper Java 客户端的 KeeperException.Code。它只表达错误分类,实际项目还要结合操作类型、幂等键和重试次数。

java
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;
    };
}

预期行为

text
CONNECTIONLOSS -> QUERY_THEN_DECIDE
BADVERSION -> RETRY_AFTER_REFRESH
SESSIONEXPIRED -> REBUILD_SESSION
NONODE -> FAIL_FAST

NoNode 和 NodeExists 是否真正失败仍取决于业务语义。例如幂等创建固定路径时,NodeExists 可能表示前一次请求已经成功,此时应读取并比对节点数据,而不是直接报错。

处理不确定写入

为每次业务写入设计可查询的唯一标识。创建任务节点可把业务请求 ID 放进节点名或数据中;连接丢失后先检查该标识是否存在,再决定是否重试。

顺序节点更难通过返回路径确认结果。可在节点数据中写入唯一请求 ID,重连后扫描限定范围并匹配;扫描范围必须受控,不能每次遍历超大目录。

处理版本冲突

BadVersion 是乐观并发控制生效的正常结果,不应无条件循环重试。客户端应重新读取数据和 Stat.version,判断新值是否仍适用,再使用新版本提交。

若更新具有覆盖风险,应把冲突返回业务层;若更新可交换或可合并,才适合在限定次数内重新计算后重试。重试必须带退避和上限,避免竞争激烈时形成活锁。

处理会话失效

SessionExpired 表示旧会话无法恢复。旧会话创建的临时节点已经或即将被服务端删除,旧 Watch 也不能继续依赖。客户端需要创建新会话,并重新注册服务、选举候选、锁和监听。

ConnectionLoss 期间不要立即假定临时节点已消失;只有确认连接状态进入 LOST 或收到 SessionExpired 后,才按新会话流程重建资源。

诊断记录与验证

每条错误日志至少记录操作类型、路径、错误码、会话 ID、请求 ID、重试次数和耗时。不要记录敏感节点内容,也不要只输出异常堆栈而缺少业务上下文。

故障演练时分别注入短暂断网、会话超时和并发版本冲突,验证不确定写入先查询、版本冲突不会无限重试、会话失效后旧锁和旧选举资格不再被使用。

本课总结

  • ConnectionLoss 和 OperationTimeout 代表结果不确定,不能直接等同于失败
  • NoNode、NodeExists 和 BadVersion 要结合业务前置条件处理
  • SessionExpired 必须创建新会话并重建临时节点、选举和监听状态

下一课预告

下一课进入生产级综合实践,先把服务注册、配置监听、主节点选举和任务互斥整合为一个可验收的项目架构。

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

目录与阅读设置

阅读设置

17

记录一个想法

常见错误码诊断

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

登录哪都通