错误与重试

规划 API： 本页说明 runtime 发布后的错误与恢复策略。commflow@0.0.2 尚未提供 request、SSE、RPC 或 socket runtime；当前可运行导出见当前版本快速开始。

如何使用本页

先按结果分类判断调用是否收到了有效响应，再决定重试、降级或暴露给业务。安装、导入、Node 版本或当前导出问题见 FAQ 与排错。

结果分类

commflow 的错误模型区分三类结果：

类型	默认行为	用户怎么处理
HTTP 4xx/5xx	request 默认返回 `Response`	用 `response.ok` 或 failure helper 判断。
timeout / network / aborted	抛出结构化错误	根据 `error.kind` 决定重试、告警或降级。
hook secondary failure	不覆盖主结果	记录日志或诊断信息。

这样的边界能避免一个常见误区：HTTP 500 不一定等于 transport error；它仍然是服务端给出了 HTTP 响应。

Request 错误处理

推荐写法是先判断 HTTP 响应，再捕获真正的 transport failure。

try {
  const response = await request.get('/users/42');

  if (!response.ok) {
    return null;
  }

  return await response.json();
} catch (error) {
  throw error;
}

目标错误类型：

`error.kind`	含义	常见处理
`timeout`	单次调用超过 `timeout`	可重试、告警或降级。
`network`	DNS、连接、TLS 或 socket 层失败	可重试；需要记录上游地址。
`aborted`	用户或宿主主动取消	通常不重试。
`config`	配置缺失或不合法	修配置，不应自动重试。
`hook`	可阻断 hook 失败	修 hook；保留原始错误链。

重试策略

重试不是越多越好。建议按“是否幂等、失败是否短暂、用户是否能承受延迟”决定。

场景	建议
GET / HEAD	通常可以启用少量 retry。
POST 创建资源	默认谨慎，除非有幂等键。
支付、扣款、库存扣减	默认不自动 retry，除非业务协议明确支持幂等。
SSE 断线	可按退避策略重连。
socket 断线	可重连，但要处理鉴权过期和重复订阅。

最小目标配置：

const request = createCommflowRequestClient({
  retry: 2,
  retryDelay: (attempt) => attempt * 200
});

retry 表示额外尝试次数；retryDelay 表示下一次尝试前的等待时间。SSE 和 socket 使用 reconnect，不使用 request 的 retry 字段。

Hook secondary failure

afterResponse、onRetry 和 onError 这类观察型 hook 失败时，不应该把一个已经成功的主请求改成失败。

Hook	secondary failure 目标行为
`afterResponse`	记录失败，但返回原始响应。
`onRetry`	记录失败，但不取消既定 retry。
`onError`	记录失败，但不覆盖原始错误。

只有 beforeRequest 这类会影响请求构造的 hook 抛错时，才应阻断请求。

排错入口

现象	去哪里
当前包没有 `createCommflowRequestClient`	FAQ 与排错
不知道 timeout / retry 怎么配置	配置指南
不知道 request、SSE、RPC、socket 选哪个	运行时指南
VextJS 接入后行为变化	接入 VextJS

#错误与重试

#如何使用本页

#结果分类

#Request 错误处理

#重试策略

#Hook secondary failure