urql retryExchange 完全指南:@urql/exchange-retry 的重试策略、指数退避与故障转移实践
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 传递
}
两个值得注意的细节:
- 成功的 Operation 会重置计数:当结果无错误时,若
context.retry存在,会将count归零、delay置空(见 retryExchange.ts)。测试用例should reset the retry counter if an operation succeeded first(retryExchange.test.ts)专门验证了这一行为,确保重试状态不会跨成功请求残留。 - 多次并发 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 参考、实战指南 与 源码实现。