Relay 缓存数据的存续性:理解 Relay 垃圾回收、Query Retention 与 GC 策略配置

原创2026-09-22 15:54:471,918 阅读
文章标签:前端开发工具

Relay 缓存数据的存续性:理解 Relay 垃圾回收、Query Retention 与 GC 策略配置

Relay 的核心设计之一是内置的规范化缓存(normalized in-memory store),它让应用可以复用已获取的数据,从而在返回已访问过的页面时无需重新等待网络请求。但要真正做到"按需复用缓存",前提是理解这些数据在 Store 中是否还存在、以及存在多久。本篇技术指南围绕 Relay v18 文档中的 "Presence of Data" 主题展开,结合 relay-runtime 源码,完整讲解 Relay 垃圾回收(Garbage Collection)的运作机制、environment.retain 的查询保留(Query Retention)用法,以及 gcScheduler、gcReleaseBufferSize 两个 GC 策略配置项的实际含义与底层实现。

读完本文,你将能够:判断一份查询数据在何时进入/离开 Relay Store,正确使用 retain() 让关键数据在组件卸载后依然存活,并学会通过 Relay Store 的 GC 配置项调整数据保留策略,以支撑"返回已访问页面秒开"的缓存复用体验。

数据在 Relay Store 中的存续性(Presence of Data)

在考虑复用 Relay Store 中已缓存的数据时,首先要理解这些数据的生命周期:它们是否存在于 Store 中,以及会存在多久。

根据官方文档的核心结论,可以归纳为两条基本事实:

  1. 已渲染的查询数据一般都在 Store 中:对于某个查询(query),只要它被成功获取过一次,并且该查询正在屏幕上被组件渲染,那么它的数据就存在于 Store 中,可被其他查询、片段或未来的同组件实例复用。
  2. 从未获取过的数据一定缺失:如果某个查询从未被获取过,它的数据自然不存在于 Store 中,无法直接复用。

但即便获取了大量不同查询的数据,Relay 也不可能把它们无限期地全部保存在内存中——随着时间推移,缓存会变得过大且过于陈旧。因此,Relay 会运行一个名为 Garbage Collection(垃圾回收,GC) 的过程,主动删除不再使用的数据。

Relay 中的垃圾回收(Garbage Collection)

Relay 对本地内存 Store 执行垃圾回收的方式是:删除任何不再被应用中任何组件引用的数据。

从源码实现看,这一机制位于 RelayModernStore.js 中:

  • Store 内部通过 _roots(一个 Map)记录所有当前"根"查询条目,每个条目包含 operation(操作描述符)、refCount(引用计数)、epoch(写入纪元)与 fetchTime(获取时间)等元数据;
  • GC 的执行主体是一个 generator 函数 _collect(),它遍历 _roots 中所有仍然有效的根,调用 RelayReferenceMarker.js 的 mark 方法遍历标记所有仍可达的记录(record),并在每个操作之间通过 yield 让出执行权,避免长时间阻塞主线程;
  • 标记完成后,未被任何有效根引用的记录即被判定为"可回收",从内存中删除。

这带来一个与"复用缓存"目标的潜在冲突:如果数据被删除得太早,在后续尝试复用它之前就被回收,那么复用时仍然需要等待网络请求,无法做到秒开。为此,官方文档指出本小节的核心目标:确保你想复用的数据,在被需要的时间内始终保留在缓存中。

:::note 通常你不需要操心垃圾回收和数据保留的配置——这部分应由应用基础设施在 RelayEnvironment 层面统一配置。下文内容更多作为原理与参考。 :::

Query Retention:主动保留查询数据

保留(Retaining)一个查询,是向 Relay 表明:该查询及其变量对应的数据不应被垃圾回收。

其语义有两个关键点:

  • 多个调用方可以同时保留同一个查询:retain 使用引用计数(refCount)管理,Store 中每个根条目记录了当前的保留次数;
  • 只要至少有一个调用方还在保留,该查询的数据就不会被删除;当最后一个保留被释放(dispose)后,该查询才进入"可被回收"的状态。

默认行为:组件挂载期间自动保留

默认情况下,任何使用 useQueryLoader / usePreloadedQuery 或 Relay 其他查询 API 的组件,会在挂载期间自动保留其查询数据。组件卸载后,Relay 会释放(release)该查询——这意味着从那一刻起,该查询的数据在未来的任何时刻都有可能被 GC 删除。

手动保留:environment.retain

如果你需要在组件生命周期之外保留某个特定查询,可以使用 environment.retain 操作:

// Retain query; this will prevent the data for this query and
// variables from being garbage collected by Relay
const disposable = environment.retain(queryDescriptor);

// Disposing of the disposable will release the data for this query
// and variables, meaning that it can be deleted at any moment
// by Relay's garbage collection if it hasn't been retained elsewhere
disposable.dispose();

environment.retain 接收一个 OperationDescriptor(操作描述符),返回一个 Disposable。调用 disposable.dispose() 会释放该查询。要构造 queryDescriptor,需要配合 relay-runtime 提供的工具函数,完整的用法可参考 Retaining Queries:

const {
  createOperationDescriptor,
  getRequest,
  graphql,
} = require('relay-runtime');

// Query graphql object
const query = graphql`...`;

// Construct Relay's internal representation of the query
const queryRequest = getRequest(query);
const queryDescriptor = createOperationDescriptor(
  queryRequest,
  variables,
);

// Retain query; this will prevent the data for this query and
// variables from being garbage collected by Relay
const disposable = environment.retain(queryDescriptor);

:::note Relay 会根据任何正在渲染数据的挂载查询组件自动管理查询数据保留,因此在业务代码中通常不需要直接调用 retain。对于高级或特殊场景(例如在 Router 等基础设施层为页面预取并保留数据),查询保留一般也应在基础设施层统一处理。 :::

手动保留的价值在于:即使查询组件已经卸载,只要调用方仍未 dispose,其他组件或未来重新挂载的同一组件实例,依然可以复用这些被保留的数据,实现免网络请求的即时渲染。

源码层面的保留语义

retain 的实现细节印证了上述语义(见 RelayModernStore.js):

  • 首次 retain 时,Store 会在 _roots 中为该查询创建条目,refCount 置为 1;
  • 后续再次 retain 同一个查询,refCount 递增;
  • dispose() 每次递减 refCount,且保证每个 Disposable 只能释放一次;
  • 当 refCount 归零时,若查询已超出 queryCacheExpirationTime(查询缓存过期时间,若配置了)设定的期限,则直接从 _roots 中删除并调度 GC;否则将该查询推入释放缓冲区(release buffer)(见下文)。

控制 Relay 的垃圾回收策略

可以通过两个选项来控制 Relay Store 的垃圾回收行为。它们都作为构造选项传给 Store(在 RelayModernStore.js 的构造函数中被解析)。

GC Scheduler(GC 调度器)

gcScheduler 是一个提供给 Relay Store 的函数,用于决定 GC 执行应在何时被调度运行:

// Sample scheduler function
// Accepts a callback and schedules it to run at some future time.
function gcScheduler(run: () => void) {
  resolveImmediate(run);
}

const store = new Store(source, {gcScheduler});

使用要点:

  • 默认值:如果不提供 gcScheduler,Relay 会使用 resolveImmediate 函数调度垃圾回收(源码中 this._gcScheduler = options?.gcScheduler ?? resolveImmediate;,对应工具实现位于 resolveImmediate.js)。
  • 自定义调度:你可以提供自己的调度函数,让 GC 调度比默认更不激进(less aggressive),例如基于时间间隔、React Scheduler 的优先级,或任何其他启发式策略。
  • 约定:按照约定,调度器实现不应立即执行回调,而应将回调安排到未来某个时刻运行,避免 GC 抢占渲染与交互的关键路径。

从类型定义看,Scheduler 被定义为 (callback: () => void) => void(见 RelayStoreTypes.d.ts),即"接收一个回调并将其调度到未来某个时间运行"。

在源码中,scheduleGC() 会将 GC 生成器与调度器串联起来(RelayModernStore.js):首次调用通过 this._gcScheduler(this._gcStep) 启动 GC;_gcStep 每次推进生成器一步,若未完成则再次通过 this._gcScheduler(this._gcStep) 调度下一步。这样 GC 就成为一个分步执行、可被外部调度器控制节奏的过程。

GC Release Buffer Size(GC 释放缓冲区大小)

Relay Store 内部维护一个释放缓冲区(release buffer),用于在查询被其原始持有者释放(默认即渲染该查询的组件卸载时)之后,仍然临时保留一定数量(可配置)的查询。这使得用户返回之前访问过的页面、标签页或内容区块时,更有可能复用已有数据。

配置方式是在创建 Relay Store 时指定 gcReleaseBufferSize 选项:

const store = new Store(source, {gcReleaseBufferSize: 10});

使用要点:

  • 缓冲区大小为 0 等价于没有释放缓冲区,意味着查询被释放后会立即被回收;
  • 默认值:默认情况下,环境的释放缓冲区大小为 10。这一默认值在源码中对应 DEFAULT_RELEASE_BUFFER_SIZE = 10 常量(见 RelayModernStore.js),并通过 options?.gcReleaseBufferSize ?? DEFAULT_RELEASE_BUFFER_SIZE 生效。

释放缓冲区的底层运作

从源码可以看出释放缓冲区是"临时根 + 先进先出淘汰"的组合机制:

  • 当某个查询操作发布数据后如果并未被 retain,_recordSourceOperation 会在缓冲区还有空间时,以 refCount: 0 的"临时根条目"形式将其记录在 _roots 中,并同时推入 _releaseBuffer 数组(RelayModernStore.js)。注意这里只对 operationKind === 'query' 的查询生效。
  • _pushToReleaseBuffer 在缓冲区超出上限时,会淘汰最久加入(FIFO,shift())的条目,将其从 _roots 中删除并调度一次 GC(RelayModernStore.js)。
  • 如果某个已进入释放缓冲区的查询被重新 retain,Store 会先把它从缓冲区中移除,再递增其 refCount,以维护"缓冲区条目 refCount 均为 0"的不变量(RelayModernStore.js)。
  • 在 GC 收集阶段,位于释放缓冲区中的记录同样会被 RelayReferenceMarker.mark 标记为可达,因而不会被回收(RelayModernStore.js)。

简单来说:释放缓冲区就是"最近释放过的查询的临时庇护所",它权衡了内存占用与缓存复用率——越大越有利于回访复用,但也占用更多内存;gcReleaseBufferSize: 0 则代表完全不保留已释放的数据。

实际应用建议

结合文档与源码,可以给出如下实践建议:

  1. 默认优先信任 Relay 的自动管理:使用 useQueryLoader / usePreloadedQuery 等 API 时,Relay 已在组件挂载期间自动 retain,组件卸载后自动 release,配合默认大小为 10 的释放缓冲区,多数导航回访场景都能命中缓存。
  2. 跨页面/跨路由复用需显式 retain:当某个查询的数据需要在组件卸载后依然保留(例如路由切换后预加载的详情页数据、Tab 切换频繁的场景),应在基础设施层(如 Router)调用 environment.retain(queryDescriptor),并在合适的时机 dispose(),形成明确的"保留-释放"配对。
  3. 用 gcReleaseBufferSize 调节回访体验与内存的平衡:回访频繁的应用可以适当调大(默认 10);内存敏感或数据时效性强的应用可以调小,甚至设为 0 让数据立即释放。
  4. 用 gcScheduler 避免 GC 抢占关键渲染:默认的 resolveImmediate 调度在宏任务中执行,如果页面渲染负担较重,可自定义调度器将 GC 延后到空闲时段(如基于时间或调度优先级),并遵守"不立即执行回调"的约定。

相关测试与延伸阅读

登录后查看全文
relay