Relay 查询渲染完整指南:usePreloadedQuery、useQueryLoader 与 useLazyLoadQuery 实战
Relay 查询渲染完整指南:usePreloadedQuery、useQueryLoader 与 useLazyLoadQuery 实战
本篇技术指南以 Relay v17 文档 Queries 为核心骨架,系统讲解 Relay 中 GraphQL Query 的定义与三种数据获取/渲染方式:使用 usePreloadedQuery 渲染预加载查询、使用 useQueryLoader 与 loadQuery 提前发起请求(render-as-you-fetch),以及使用 useLazyLoadQuery 在渲染时懒加载。文章结合本仓库 react-relay 包的 Hook 源码与测试用例,说明各 API 的参数、内部机制与适用场景,帮助你写出数据加载更快、无瀑布流请求的 Relay 应用。
什么是 GraphQL Query
在 Relay 中,GraphQL Query 组成,这些字段描述了要从服务器请求的数据。能查询什么取决于服务器暴露的 GraphQL Schema——Schema 描述了可供查询的数据形态。
查询可以作为网络请求发送到服务器,同时可携带查询所使用的一组可选 variables。服务器响应是一个与查询形状匹配的 JSON 对象。例如:
query UserQuery($id: ID!) {
user(id: $id) {
id
name
...UserFragment
}
viewer {
actor {
name
}
}
}
fragment UserFragment on User {
username
}
对应的示例响应:
{
"data": {
"user": {
"id": "4",
"name": "Mark Zuckerberg",
"username": "zuck"
},
"viewer": {
"actor": {
"name": "Your Name"
}
}
}
}
注意:在 Relay 中,query 是通过 graphql 模板标签声明的。编译器会对每个 query 自动生成对应的 Flow/TypeScript 类型与运行时产物(本仓库的测试工程 compiler/test-project/src/generated 即展示了生成的 .graphql.js 文件形态),这正是后文各 Hook 能够获得精确类型推导的基础。
渲染查询:usePreloadedQuery
要在 Relay 中渲染一个查询,可以使用 usePreloadedQuery Hook。它接收一个查询定义和一个查询引用(query reference),返回该查询及引用对应的数据:
import type {HomeTabQuery} from 'HomeTabQuery.graphql';
import type {PreloadedQuery} from 'react-relay';
const React = require('React');
const {graphql, usePreloadedQuery} = require('react-relay');
type Props = {
queryRef: PreloadedQuery<HomeTabQuery>,
};
function HomeTab(props: Props) {
const data = usePreloadedQuery(
graphql`
query HomeTabQuery($id: ID!) {
user(id: $id) {
name
}
}
`,
props.queryRef,
);
return (
<h1>{data.user?.name}</h1>
);
}
对上面示例的拆解:
usePreloadedQuery接收一个graphql查询和一个PreloadedQuery引用,返回该查询已获取到的数据。PreloadedQuery(此处即queryRef)是一个描述并引用我们查询"实例"的对象,该实例正在(或已经)被获取。如何真正发起获取在下一节介绍;如果渲染时查询仍在进行中,如何展示加载状态见 Loading States with Suspense 一节。
- 与 fragments 类似,组件会自动订阅查询数据的更新:如果该查询的数据在应用任意位置被更新,组件会自动以最新数据重新渲染。
usePreloadedQuery还接收一个 Flow 类型参数,对应查询的 Flow 类型,此处为HomeTabQuery。- Relay 编译器会自动为声明的查询生成 Flow 类型,可从生成文件中导入,命名格式为:
<query_name>.graphql.js。 - 注意
data无需显式类型注解即已具备正确的 Flow 类型,且基于 GraphQL schema 中的类型推导。例如上面data的类型为{ user: ?{ name: ?string } }。
- Relay 编译器会自动为声明的查询生成 Flow 类型,可从生成文件中导入,命名格式为:
- 在尝试渲染查询之前,请确保应用根部通过 Relay Environment Provider 提供了 Relay environment。
从源码看,usePreloadedQuery 的核心逻辑位于 packages/react-relay/relay-hooks/usePreloadedQuery.js:它通过 useRelayEnvironment() 获取环境,用 useMemoOperationDescriptor 基于查询、preloadedQuery.variables 和 preloadedQuery.networkCacheConfig 构造 operation,再交给 useLazyLoadQueryNode 统一执行。其中还有几个重要的内部保障:
- 环境一致性检查:当传入的 preloaded query 是用另一个 environment 创建、而当前 context 环境不同时,源码会输出一条警告("usePreloadedQuery was passed a preloaded query that was created with a different environment..."),并回退到用当前环境重新执行查询;
- 已释放引用检查:如果传入的
preloadedQuery已被dispose,会给出警告,因为释放意味着该查询数据将可能被垃圾回收; - 源码级去重:
fetchObservable会复用预加载时保存的sourceobservable(通过source.ifEmpty(fallbackFetchObservable)),若 source 为空或环境不匹配,则回退到fetchQuery去重执行,避免重复请求。
对应的行为在 usePreloadedQuery-test.js 中有覆盖。
为渲染而获取查询:useQueryLoader 与 loadQuery
除了渲染查询,我们还需要从服务器获取它。通常我们希望在应用根部附近获取查询,并且只保留一个或少数几个能够聚合(accumulate)渲染屏幕所需的全部数据的查询(参见 fragments 中的组合方式)。理想情况下,我们应该在开始渲染应用之前就尽早获取它们。
使用 useQueryLoader
要在稍后渲染之前获取查询,可以使用 useQueryLoader Hook:
import type {HomeTabQuery as HomeTabQueryType} from 'HomeTabQuery.graphql';
import type {PreloadedQuery} from 'react-relay';
const HomeTabQuery = require('HomeTabQuery.graphql')
const {useQueryLoader} = require('react-relay');
type Props = {
initialQueryRef: PreloadedQuery<HomeTabQueryType>,
};
function AppTabs(props) {
const [
homeTabQueryRef,
loadHomeTabQuery,
] = useQueryLoader(
HomeTabQuery,
props.initialQueryRef, /* e.g. provided by router */
);
const onSelectHomeTab = () => {
// Start loading query for HomeTab immediately in the event handler
// that triggers navigation to that tab, *before* we even start
// rendering the target tab.
// Calling this function will update the value of homeTabQueryRef.
loadHomeTabQuery({id: '4'});
// ...
}
// ...
return (
screen === 'HomeTab' && homeTabQueryRef != null ?
// Pass to component that uses usePreloadedQuery
<HomeTab queryRef={homeTabQueryRef} /> :
// ...
);
}
上面的例子有些刻意,但我们提炼一下它的要点:
- 我们在
AppTabs组件内调用useQueryLoader。- 它接收一个查询——此处是我们的
HomeTabQuery(上一节声明的查询),可以通过 require 自动生成的文件'HomeTabQuery.graphql'获得。 - 它接收一个可选的初始
PreloadedQuery,作为存在 state 中、由useQueryLoader返回的homeTabQueryRef的初始值。 - 它同样接收一个 Flow 类型参数,对应查询的 Flow 类型,此处为
HomeTabQueryType,同样可以从自动生成的文件'HomeTabQuery.graphql'获得。
- 它接收一个查询——此处是我们的
- 调用
useQueryLoader可以得到两样东西:homeTabQueryRef:一个?PreloadedQuery对象,描述并引用正在(或已经)获取的查询实例。如果我们还没有调用loadHomeTabQuery获取该查询,这个值会是null。loadHomeTabQuery:一个函数,它会从服务器获取该查询的数据(如果尚未缓存的话),并接收一个包含查询期望的 variables 的对象,此处为{id: '4'}(Relay 如何复用缓存数据详见 Reusing Cached Data For Render)。调用该函数还会把homeTabQueryRef更新为一个PreloadedQuery实例。- 注意:传给该函数的
variables会经过 Flow 检查,确保你传入的值与 GraphQL 查询期望的匹配。 - 注意:我们是在导致
HomeTab被渲染的事件处理器中调用该函数的。这让我们能尽可能早地为屏幕发起数据请求,甚至在新的 tab 开始渲染之前。- 事实上,
loadQuery若在 React 的渲染阶段被调用会抛出错误!
- 事实上,
- 注意:传给该函数的
- 注意:
useQueryLoader会在组件卸载时自动 dispose 所有已加载的查询。Dispose 一个查询意味着 Relay 不再为该查询实例在缓存中保留数据(查询数据的生命周期详见 Reusing Cached Data For Render)。此外,如果 dispose 发生时请求仍在进行中,该请求会被取消。 - 我们的
AppTabs组件渲染上一节的HomeTab组件,并把对应的查询引用传给它。注意父组件拥有该查询数据的生命周期:当它卸载时,如上所述会 dispose 该查询。 - 最后,在尝试使用
useQueryLoader之前,请确保应用根部通过 Relay Environment Provider 提供了 Relay environment。
从 useQueryLoader.js 源码可以看到三个关键内部机制:
- 初始引用处理:初始
initialQueryReference(可能为null)被包装为内部状态;当父组件传入新的初始引用时,Hook 会将其纳入undisposedQueryReferencesRef跟踪集合。 - 引用生命周期管理:每次调用
loadQuery得到的引用都会加入undisposedQueryReferencesRef;在组件提交(commit)后,通过 useEffect 迭代该集合,dispose 掉除了当前提交引用之外的所有旧引用;组件卸载时,disposeAllRemainingQueryReferences会释放所有剩余引用(live query 调用dispose(),普通查询调用releaseQuery())。这保证了多次调用loadQuery不会在 Relay store 中泄漏数据。 - 返回值三元组:Hook 实际返回
[queryReference(可能为 null), queryLoaderCallback, disposeQuery]。第三个返回值disposeQuery可将当前 query ref 重置为 null。
在组件外部直接调用 loadQuery
有时你想在父组件的上下文之外发起请求,例如获取应用初始加载所需的数据。这种情况下可以直接使用 loadQuery API,而不必借助 useQueryLoader:
import type {HomeTabQuery as HomeTabQueryType} from 'HomeTabQuery.graphql';
const HomeTabQuery = require('HomeTabQuery.graphql')
const {loadQuery} = require('react-relay');
const environment = createEnvironment(...);
// At some point during app initialization
const initialQueryRef = loadQuery<HomeTabQueryType>(
environment,
HomeTabQuery,
{id: '4'},
);
// ...
// E.g. passing the initialQueryRef to the root component
render(<AppTabs initialQueryRef={initialQueryRef} initialTab={...} />)
- 在此例中,我们直接调用
loadQuery函数得到一个PreloadedQuery实例,稍后可以把它传给使用usePreloadedQuery的组件。 - 这种情况下,我们期望根组件
AppTabs管理查询引用的生命周期,并在适当的时候(如果需要的话)dispose 它。 - 我们故意把"应用初始化"的细节写得含糊,因为不同应用差异很大。这里的关键是:我们应该在开始渲染根组件之前就拿到查询引用。事实上,
loadQuery在 React 渲染阶段被调用会抛出错误!
从 loadQuery.js 源码看,loadQuery 每次调用都会:
- 自增一个内部
fetchKey(从100001开始),确保每次创建的 query reference 都被独立求值,避免 Suspense 缓存误复用旧结果; - 解析默认
fetchPolicy:普通查询默认为'store-or-network',live query 或启用执行期 resolver 的查询默认为'store-and-network',纯客户端查询(无id也无text)则为'store-only'; - 将
networkCacheConfig强制合并force: true,绕过网络层查询响应缓存; - 通过
environment.retain(operation)持有数据,并通过fetchQueryDeduped同时去重"原始网络请求"与"operation 执行"两个层面——即使loadQuery在 query AST 可用之前被多次调用,网络请求也只会发起一次; - 若传入的是
PreloadableConcreteRequest(preloadable query),而查询模块尚未同步可用,则立即发起网络请求,并通过PreloadableQueryRegistry.onLoad在模块加载完成后衔接执行; - 返回对象包含
cancelNetworkRequest、dispose()、releaseQuery()等方法以及fetchKey、fetchPolicy、variables、source等字段,其中source只有在确实发起过网络请求时才存在(didMakeNetworkRequest)。
Render as You Fetch
上面的示例展示了如何把"获取数据"与"渲染数据"分离,以便尽可能早地开始请求(而不是等到组件渲染才开始),从而更早地向用户展示内容。这也有助于防止瀑布式(waterfall)往返请求,并让我们对请求何时发生拥有更多控制力和可预测性——如果我们在渲染期间才发起请求,就难以确定请求何时(或应当)发生。这与 React Suspense 下的 "render-as-you-fetch" 模式完美契合。
这是 Relay 获取数据的首选模式,适用于多种场景:应用初始加载、后续导航,以及一般性地用于那些初始隐藏、通过交互(如菜单、弹窗、对话框等)随后才显示、且需要额外数据的 UI 元素。
在仓库的 useQueryLoader-test.js 与 useQueryLoader-multiple-calls-test.js 测试中,可以找到关于"在事件处理器中提前加载、渲染时消费查询引用"以及"多次调用 loadQuery 时的引用释放"的完整行为验证。
渲染期间懒加载查询:useLazyLoadQuery
另一种获取查询的方式是在组件渲染时才懒加载。不过如前所述,首选模式是在渲染之前就开始获取。若不加小心地使用懒加载,可能触发嵌套或瀑布式往返请求,降低性能。
要懒加载查询,可以使用 useLazyLoadQuery Hook:
const React = require('React');
const {graphql, useLazyLoadQuery} = require('react-relay');
function App() {
const data = useLazyLoadQuery(
graphql`
query AppQuery($id: ID!) {
user(id: $id) {
name
}
}
`,
{id: '4'},
);
return (
<h1>{data.user?.name}</h1>
);
}
要点拆解:
useLazyLoadQuery接收一个 graphql 查询和该查询的 variables,返回该查询获取到的数据。variables 是一个对象,包含 GraphQL 查询内部引用的 variables 的值。- 与 fragments 类似,组件自动订阅查询数据的更新:如果该查询的数据在应用任意位置被更新,组件自动以最新数据重新渲染。
useLazyLoadQuery额外接收一个 Flow 类型参数,对应查询的 Flow 类型,此处为AppQuery。- 记住 Relay 会为所有声明的查询自动生成 Flow 类型,可导入并与
useLazyLoadQuery一起使用。这些类型位于生成文件中,命名格式为<query_name>.graphql.js。 - 注意
variables会被 Flow 检查,确保传入值与 GraphQL 查询期望的匹配。 - 注意
data已具备正确的 Flow 类型,无需显式注解,且基于 GraphQL schema 类型推导。例如上面data的类型为{ user: ?{ name: ?string } }。
- 记住 Relay 会为所有声明的查询自动生成 Flow 类型,可导入并与
- 默认情况下,组件渲染时 Relay 会获取该查询的数据(如果尚未缓存),并将其作为
useLazyLoadQuery的调用结果返回。加载状态如何展示详见 Loading States with Suspense,Relay 如何复用缓存数据详见 Reusing Cached Data For Rendering。 - 注意:如果你重新渲染组件并传入与之前不同的查询 variables,会导致查询以新 variables 重新获取,并可能以不同数据重新渲染。
- 最后,在尝试渲染查询之前,请确保应用根部通过 Relay Environment Provider 提供了 Relay environment。
从 useLazyLoadQuery.js 源码看,该 Hook 支持一个可选的 options 对象,关键选项及默认值如下:
| 选项 | 类型 | 说明 |
|---|---|---|
fetchPolicy |
FetchPolicy |
决定是否使用缓存数据、何时基于 store 中现有缓存发起网络请求。取值:'store-or-network'(默认,有缓存就复用,仅当查询数据缺失时才发请求)、'store-and-network'(复用缓存但总是发请求)、'network-only'(不复用缓存,总是发请求)、'store-only'(只读缓存,永不发请求,适合处理完全本地的数据,详见 local data updates 相关章节) |
fetchKey |
string | number |
传入一个 fetchKey 可以强制组件重新渲染时重新求值当前查询与 variables,即使 variables 没变、甚至组件没有重新挂载(类似给 React 组件传不同 key 使其重挂载)。如果 fetchKey 与上次渲染不同,当前查询会基于 store 重新求值,并可能根据当前 fetchPolicy 与缓存状态重新获取 |
networkCacheConfig |
CacheConfig |
默认值为 {force: true}。包含针对网络层的缓存配置。网络层可能还有额外的查询响应缓存,会为相同查询复用网络响应。要完全绕过该缓存(默认行为),传入 {force: true} |
UNSTABLE_renderPolicy |
RenderPolicy |
未文档化的选项 |
在实现上,useLazyLoadQuery 会先通过 useMemoOperationDescriptor 构造 operation(若未显式传 networkCacheConfig,默认使用 {force: true}),再调用 fetchQuery(environment, query) 创建 fetch observable,最终交由 useLazyLoadQueryNode.js 完成核心工作:基于 cacheIdentifier(由 environment、query、fetchPolicy、renderPolicy 与 forceUpdateKey/fetchKey 组合而成)调用 QueryResource.prepareWithIdentifier 获取查询资源,并通过 QueryResource.retain 在组件生命周期内持有数据、在清理阶段释放。这也是"组件重新渲染且 variables 变化时查询会被重新获取"这一行为的底层来源——variables 变化会改变 operation 与 cache identifier,从而触发重新求值。相关行为在 useLazyLoadQueryNode-test.js 与 loadQuery-source-behavior-test.js 中有充分覆盖。
三种 API 选型建议与注意事项
综合本文,可以给出如下选型结论:
- usePreloadedQuery(渲染已预加载的查询):数据在渲染前就已开始获取(由
useQueryLoader/loadQuery完成),组件只负责消费PreloadedQuery引用并订阅更新。这是与 render-as-you-fetch 模式搭配的渲染端 API。 - useQueryLoader / loadQuery(提前获取):在事件处理器、应用初始化、导航回调等非渲染时机发起请求,拿到
PreloadedQuery后传给usePreloadedQuery渲染。这是 Relay 推荐的获取方式,能有效避免瀑布流请求。 - useLazyLoadQuery(渲染时获取):组件首次渲染时才触发请求,使用简单,适合快速原型或确实无法提前获取的场景;但要注意其可能引发嵌套/瀑布式请求的性能代价,且 variables 变化会触发重新获取。
无论选择哪种 API,都需要牢记三个通用前提:
- 应用根部必须提供 Relay Environment Provider(对应 API 参考见 relay-environment-provider),所有 Hook 都依赖它取得当前 environment;
- 所有 query 都通过
graphql模板标签声明,编译器会生成<query_name>.graphql.js类型与运行时产物,应始终导入/引用生成文件以获得类型安全; loadQuery(包括useQueryLoader内部调用)禁止在 React 渲染阶段调用,否则会抛出错误;请在事件处理器、effect 或应用初始化流程中调用。