Relay 查询渲染完整指南:usePreloadedQuery、useQueryLoader 与 useLazyLoadQuery 实战

原创2026-09-22 10:02:141,759 阅读
文章标签:前端开发工具

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 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 会复用预加载时保存的 source observable(通过 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 源码可以看到三个关键内部机制:

  1. 初始引用处理:初始 initialQueryReference(可能为 null)被包装为内部状态;当父组件传入新的初始引用时,Hook 会将其纳入 undisposedQueryReferencesRef 跟踪集合。
  2. 引用生命周期管理:每次调用 loadQuery 得到的引用都会加入 undisposedQueryReferencesRef;在组件提交(commit)后,通过 useEffect 迭代该集合,dispose 掉除了当前提交引用之外的所有旧引用;组件卸载时,disposeAllRemainingQueryReferences 会释放所有剩余引用(live query 调用 dispose(),普通查询调用 releaseQuery())。这保证了多次调用 loadQuery 不会在 Relay store 中泄漏数据。
  3. 返回值三元组: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 会获取该查询的数据(如果尚未缓存),并将其作为 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 选型建议与注意事项

综合本文,可以给出如下选型结论:

  1. usePreloadedQuery(渲染已预加载的查询):数据在渲染前就已开始获取(由 useQueryLoader/loadQuery 完成),组件只负责消费 PreloadedQuery 引用并订阅更新。这是与 render-as-you-fetch 模式搭配的渲染端 API。
  2. useQueryLoader / loadQuery(提前获取):在事件处理器、应用初始化、导航回调等非渲染时机发起请求,拿到 PreloadedQuery 后传给 usePreloadedQuery 渲染。这是 Relay 推荐的获取方式,能有效避免瀑布流请求。
  3. useLazyLoadQuery(渲染时获取):组件首次渲染时才触发请求,使用简单,适合快速原型或确实无法提前获取的场景;但要注意其可能引发嵌套/瀑布式请求的性能代价,且 variables 变化会触发重新获取。

无论选择哪种 API,都需要牢记三个通用前提:

  • 应用根部必须提供 Relay Environment Provider(对应 API 参考见 relay-environment-provider),所有 Hook 都依赖它取得当前 environment;
  • 所有 query 都通过 graphql 模板标签声明,编译器会生成 <query_name>.graphql.js 类型与运行时产物,应始终导入/引用生成文件以获得类型安全;
  • loadQuery(包括 useQueryLoader 内部调用)禁止在 React 渲染阶段调用,否则会抛出错误;请在事件处理器、effect 或应用初始化流程中调用。
登录后查看全文
relay