urql retryExchange 完全指南:@urql/exchange-retry 的重试策略、指数退避与故障转移实践

原创2026-09-24 10:57:021,653 阅读
文章标签:前端

urql retryExchange 完全指南:@urql/exchange-retry 的重试策略、指数退避与故障转移实践

本文是 urql GraphQL 客户端重试能力(@urql/exchange-retry 包中的 retryExchange)的完整技术指南。retryExchange 允许对失败的 Operation(查询、变更、订阅)进行自动重试,默认仅重试网络错误,并可通过一组细粒度选项定制延迟、退避因子、重试次数上限与触发条件。读完本文,你将掌握如何在 urql Client 中正确接入并放置重试 Exchange、理解每个配置项的底层实现原理、按错误类型定制重试策略,以及利用 retryWith 实现客户端级故障转移(Failover)。

背景与定位

retryExchange 是 @urql/exchange-retry 包导出的 Exchange 工厂函数(factory),用于让失败的 Operation 被自动重试——典型场景是上一次请求因网络错误失败。它属于 urql 的"可按需增装"能力:在 urql 的官方 API 文档中被定义为插件式 Exchange,完整配置项与用法同时在 API 参考 与 Retrying Operations 实战指南 两处文档中说明,本文以这两份文档为骨架,并结合仓库源码 retryExchange.ts、测试用例 retryExchange.test.ts 与可运行示例 with-retry 进行纵深讲解。

安装与基础接入

首先需要将 @urql/exchange-retry 与 urql 一同安装:

yarn add @urql/exchange-retry
# 或
npm install --save @urql/exchange-retry

随后在创建 urql Client 时,通过 retryExchange(options) 工厂函数生成 Exchange 并加入 exchanges 数组。以下配置中标注了各选项的默认值(这些选项并非必须全部显式传入):

import { Client, cacheExchange, fetchExchange } from 'urql';
import { retryExchange } from '@urql/exchange-retry';

// 以下均为默认值,实际使用时可省略
const options = {
  initialDelayMs: 1000,
  maxDelayMs: 15000,
  randomDelay: true,
  maxNumberAttempts: 2,
  retryIf: err => err && err.networkError,
};

const client = new Client({
  url: 'http://localhost:1234/graphql',
  exchanges: [
    cacheExchange,
    retryExchange(options), // 通过工厂函数创建 retry exchange
    fetchExchange,
  ],
});

Exchange 的放置顺序至关重要:retryExchange 应位于 fetchExchange 之前、cacheExchange 之后,这样重试只会在 Operation 已经过缓存并实际发起网络请求失败后才进行。如果放在 fetchExchange 之后,重试将无法正确包裹网络请求环节。

从源码看,retryExchange.ts 在工厂函数内部对空选项做了默认值兜底:MIN_DELAY = options.initialDelayMs || 1000、MAX_DELAY = options.maxDelayMs || 15_000、MAX_ATTEMPTS = options.maxNumberAttempts || 2、RANDOM_DELAY = options.randomDelay != null ? !!options.randomDelay : true,与文档所述默认值完全一致。

选项总览(Options)

@urql/exchange-retry 通过 RetryExchangeOptions 类型接收配置,以下是 API 文档 docs/api/retry-exchange.md 中定义的全部选项:

选项 说明 默认值(来自源码)
initialDelayMs 指定重试开始前的起始等待间隔,例如设为 1000,则 Operation 失败后等待 1 秒再重试。 1000
maxDelayMs 两次重试之间的最大延迟上限。retryExchange 会持续增大重试间隔,避免服务器同时收到其无法处理的请求洪峰;该间隔以随机 back-off 因子乘以 initialDelayMs 的方式递增(即所谓的"惊群效应"缓解策略)。 15000
randomDelay 是否启用上述随机化延迟。设为 false 时,每次重试间隔严格按 initialDelayMs 递增。 true
maxNumberAttempts 最大尝试次数(包含首次请求)。例如 2 表示首次请求失败后重试 1 次。 2
retryIf 自定义函数,对返回的错误进行判定,决定是否应重试。 err => err && err.networkError(仅网络错误)
retryWith 转换函数,允许你选择性替换被重试的 Operation,或返回空值(nullish)以放弃重试。其行为类似 retryIf:返回真值时重试(注意:retryIf 优先级更高,会覆盖此函数)。 无

每个选项在 RetryExchangeOptions 接口 中都有对应的 TSDoc 注解,可作为编辑器内的即时参考。

延迟机制:指数退避与惊群效应

maxDelayMs 的设计动机在于防止"惊群效应"(thundering herd problem):若所有客户端在失败后同时重试,服务器会在同一时刻收到大量无法处理的请求。为此,重试间隔会乘以一个随机退避因子持续增长,直到上限 maxDelayMs。

源码 retryExchange.ts 展示了精确的退避算法:

const retryCount = ++retry.count;
let delayAmount = retry.delay || MIN_DELAY;

const backoffFactor = Math.random() + 1.5; // 随机因子,取值区间 [1.5, 2.5)
if (RANDOM_DELAY) {
  // randomDelay 开启:在不超过 maxDelay 的前提下叠加随机量,避免惊群效应
  if (delayAmount * backoffFactor < MAX_DELAY) {
    delayAmount *= backoffFactor;
  } else {
    delayAmount = MAX_DELAY; // 触顶后固定为最大延迟
  }
} else {
  // randomDelay 关闭:每次按 initialDelayMs 成比例递增
  delayAmount = Math.min(retryCount * MIN_DELAY, MAX_DELAY);
}

retry.delay = delayAmount; // 延迟会写入 context,供下一次重试读取

可以提炼出两条延迟路径:

  • randomDelay: true(默认):首次失败等待 initialDelayMs(默认 1 秒);随后每次延迟乘以 Math.random() + 1.5 的随机因子(约 1.5~2.5 倍),一旦乘积达到 maxDelayMs 便封顶不再增长。这既实现了指数退避的渐增效果,又通过随机抖动打散客户端的重试节奏。
  • randomDelay: false:完全确定性递增,第 n 次重试的等待时间严格为 min(n * initialDelayMs, maxDelayMs)。例如 initialDelayMs 为 1 秒时,第一次失败等 1 秒,第二次失败等 2 秒,依此类推,同样受 maxDelayMs 封顶。

测试 retryExchange.test.ts 中的 should increase retries by initialDelayMs for each subsequent failure 用例验证了关闭随机延迟时的线性递增行为(以 advanceTimersByTime(i * initialDelayMs) 推进假时钟逐一断言)。

重试次数:maxNumberAttempts 与计数机制

maxNumberAttempts 定义总尝试次数上限,包含首次请求:默认值 2 即首次失败后仅重试一次。若希望无限重试,可显式传入 Number.POSITIVE_INFINITY。

重试计数与延迟状态保存在 Operation 的 context.retry 上,其结构为 { count: number; delay: number | null }。核心判定逻辑位于 retryExchange.ts 的结果过滤器中:

const maxNumberAttemptsExceeded =
  ((retry && retry.count) || 0) >= MAX_ATTEMPTS - 1;
if (!maxNumberAttemptsExceeded) {
  // 尚未超限:按 retryWith / retryIf 决定是否进入重试流
  ...
  nextRetryOperation(operation); // 投递到重试 Subject
  return false; // 拦截当前错误结果,不向后续 Exchange 传递
}

两个值得注意的细节:

  1. 成功的 Operation 会重置计数:当结果无错误时,若 context.retry 存在,会将 count 归零、delay 置空(见 retryExchange.ts)。测试用例 should reset the retry counter if an operation succeeded first(retryExchange.test.ts)专门验证了这一行为,确保重试状态不会跨成功请求残留。
  2. 多次并发 Operation 彼此独立:retry$ Subject 通过 mergeMap 为每个 Operation 维护独立的 RetryState,测试用例 retries if it hits an error and works for multiple concurrent operations(retryExchange.test.ts)验证了两个并发查询各自达到各自的最大尝试次数。

按错误类型定制重试:retryIf

默认情况下,retryExchange 只在 CombinedError 携带 networkError 时重试。你可以通过 retryIf 自定义判定条件,例如同时覆盖 GraphQL 错误与网络错误:

import { Client, cacheExchange, fetchExchange } from 'urql';
import { retryExchange } from '@urql/exchange-retry';

const client = new Client({
  url: 'http://localhost:1234/graphql',
  exchanges: [
    cacheExchange,
    retryExchange({
      retryIf: error => {
        return !!(error.graphQLErrors.length > 0 || error.networkError);
      },
    }),
    fetchExchange,
  ],
});

以上示例会在存在 graphQLErrors 或 networkError 时触发重试;你还可以进一步细化,只针对 graphQLErrors 中的特定错误进行判定。

仓库自带的 with-retry 示例 给出了更实用的场景:示例 Schema 会随机抛出携带扩展码 NO_SOUP 的错误,客户端仅在出现该扩展码或网络错误时才重试,并且将尝试次数上限提高到 10 次、最大延迟收紧到 500ms(见 examples/with-retry/src/App.jsx):

retryExchange({
  maxNumberAttempts: 10,
  maxDelayMs: 500,
  retryIf: error => {
    return (
      error.graphQLErrors.some(x => x.extensions?.code === 'NO_SOUP') ||
      !!error.networkError
    );
  },
}),

retryIf 的函数签名在源码中定义为 retryIf?(error: CombinedError, operation: Operation): boolean(见 retryExchange.ts),即它还会收到失败的 Operation,因此也可以实现"仅重试查询类 Operation"之类的策略。

故障转移 / 回退:retryWith

当网络故障导致部分基础设施不可用,但存在备用 GraphQL 端点(例如不同域名下不同提供商的回退服务)时,retryWith 可完成客户端级故障转移。该能力同样适用于 graphQLError 场景,例如 API 采用窗口化(windowing)部署:新版部署在 URL X,旧版保留在 URL Y。

需要注意:retryWith 提供的是按需粒度控制,不承担负载均衡职责,无法在多个端点间分摊流量。

const fallbackUrl = 'http://localhost:1337/anotherGraphql';

const options = {
  initialDelayMs: 1000,
  maxDelayMs: 15000,
  randomDelay: true,
  maxNumberAttempts: 2,
  retryWith: (error, operation) => {
    if (error.networkError) {
      const context = { ...operation.context, url: fallbackUrl };
      return { ...operation, context }; // 替换 URL 后继续重试
    }
    return null; // 返回空值则不重试
  },
};

源码对 retryWith 的处理在 retryExchange.ts:当 retryWith 存在且返回一个 Operation 时,重试流会用新 Operation 替换失败请求;返回 null / undefined 时则该结果直接放行(return true),不再重试。测试 should allow retryWhen to return new operations when retrying(retryExchange.test.ts)验证了每次重试返回的新 Operation 会被真正转发(示例中通过在 context 上递增 counter 字段断言每次重试都携带新上下文)。

组合规则:retryIf 与 retryWith 的优先级

两者同时提供时,retryIf 优先。源码中的判定逻辑清晰体现了这一规则:

if (
  !res.error ||
  (retryIf
    ? !retryIf(res.error, res.operation)
    : !retryWith && !res.error.networkError)
) {
  // 不满足重试条件:直接放行
  return true;
}

即:若定义了 retryIf,是否重试完全由 retryIf 的返回值决定,retryWith 仅在该判定通过后负责"如何构造重试的 Operation";若未定义 retryIf,则只有 retryWith 存在或错误含 networkError 时才可能重试。换言之,retryIf 是"是否重试"的闸门,retryWith 是"重试什么"的转换器。

底层机制补充:调试事件与 Teardown 保护

结合 retryExchange.ts 源码,还可补充两个对排查问题有实际价值的内部机制:

  • 调试事件:每次触发重试会派发 retryAttempt 事件(消息形如 The operation has failed and a retry has been triggered (count / MAX_ATTEMPTS),附带 retryCount 与 delayAmount 数据);当达到最大尝试次数时会派发 retryExhausted 事件(见 retryExchange.ts 与 L225-L230)。这些事件可通过 urql Devtools 或自定义调试 Exchange 观察,便于确认重试是否按预期触发。
  • Teardown 保护:重试过程中若收到针对同一 Operation key 的 teardown(卸载)事件,等待中的重试会被 takeUntil(teardown$) 取消(见 retryExchange.ts),避免组件卸载后仍发出无效请求;同时若期间有同 key 的新 query 到来(即查询自身重新发起),也会停止本次退避等待,防止叠加无意义的重试。

可运行的完整示例

仓库 examples/with-retry 提供了一个可直接运行的 React + Vite 示例,依赖 urql、@urql/core、@urql/exchange-retry 与 graphql,查询目标为 https://trygql.formidable.dev/graphql/intermittent-colors(一个会随机返回 NO_SOUP 错误以演示重试的 Schema)。运行方式:

yarn install
yarn run start
# 或
npm install
npm run start

示例中 Color.jsx 通过 useQuery 发起随机颜色查询,并利用 result.operation.context.retryCount 展示本次请求实际重试的次数,直观验证 retryExchange 的效果——这是理解本文全部配置项最快的方式。

小结

retryExchange 为 urql Client 提供了可靠的重试骨架:默认以 1 秒起始延迟、随机指数退避(上限 15 秒)、总尝试 2 次、仅网络错误触发的方式工作;通过 initialDelayMs、maxDelayMs、randomDelay、maxNumberAttempts 可精确控制退避曲线与次数,通过 retryIf 可按错误类型/错误扩展码/Operation 类型定制触发条件,通过 retryWith 可实现备用端点的客户端级故障转移。其核心状态(重试计数与延迟)随 operation.context.retry 在多次重试间传递,并在成功后自动复位,配合 teardown 保护与调试事件,构成一套可观测、可控制、可用于生产环境的容错机制。更多细节可继续阅读仓库内的 API 参考、实战指南 与 源码实现。

登录后查看全文
urql