React Suspense 与数据获取

写过几年 React 的人,大概都写过这样一段代码:拉一个接口,定义一个 isLoading,再在 JSX 里用 isLoading ? <Spinner /> : <List /> 反复横跳。一个组件还好,三五层嵌套下来,loading 状态像意大利面一样缠在一起——父组件在等,子组件也在等,中间还得判断"数据到底是空还是没回来"。

React 16.6 引入的 Suspense,就是来结这本旧账的。它把"组件在等一个异步值"变成一件声明式的事:你不用再手动管理 loading,Suspense 边界会自动兜住"挂起"状态,展示 fallback,等数据回来再恢复渲染。

一、传统 loading 状态:为什么我们都需要 Suspense

先看一个典型的"旧时代"写法:

function ArticleList() {
  const { data, isLoading, error } = useQuery({
    queryKey: ['articles'],
    queryFn: fetchArticles,
  });

  if (isLoading) return <Spinner />;
  if (error) return <ErrorMessage error={error} />;
  if (!data || data.length === 0) return <Empty />;

  return <ul>{data.map((a) => <li key={a.id}>{a.title}</li>)}</ul>;
}

单看没问题。但当一个页面由多个独立的数据块组成——文章列表、作者信息、评论区、推荐栏——每个组件都要自己处理 loading/error/empty 三态,父组件再拼装,代码很快会变成一串条件分支的堆砌。更糟的是:这些 loading 状态彼此独立,页面会出现"瀑布式闪烁"——先是列表转圈,列表回来后作者区开始转,作者回来评论区又转。用户看到的是一个不停跳动的页面。

Suspense 的核心承诺是:把"等数据"从命令式的状态管理,变成声明式的组件树表达。你只管描述"这里需要一个异步值",React 负责在它没就绪时展示 fallback。

二、Suspense 的原理:throw 一个 promise

Suspense 的机制说起来很优雅:子组件在渲染时如果发现依赖的异步值还没就绪,就 throw 一个 promise。React 捕获这个 throw 后,会向上找到最近的 <Suspense> 边界,展示它的 fallback;等 promise resolve,React 再重新尝试渲染那个子组件。

import { Suspense } from 'react';

function Page() {
  return (
    <Suspense fallback={<PageSkeleton />}>
      <ArticleList />
      <Suspense fallback={<CommentsSkeleton />}>
        <Comments />
      </Suspense>
    </Suspense>
  );
}

这里的关键认知是:Suspense 不是"数据获取库",它是一个"协调异步状态"的协议。任何能"读一个还没准备好的值就 throw promise"的东西,都可以接入 Suspense——React Query、SWR、Relay、Server Components,甚至你自己包一层资源。

手写一个最简的 Suspense 数据源,能帮你彻底想通它:

type Resource<T> = { read: () => T };

function createResource<T>(promise: Promise<T>): Resource<T> {
  let status: 'pending' | 'success' | 'error' = 'pending';
  let result: T;
  let error: unknown;

  const p = promise.then(
    (r) => { status = 'success'; result = r; },
    (e) => { status = 'error'; error = e; },
  );

  return {
    read() {
      if (status === 'success') return result;
      if (status === 'error') throw error;
      throw p; // 关键:挂起
    },
  };
}

read() 在数据没就绪时 throw promise,这就是 Suspense 的全部魔法。理解了这一点,后面所有的库集成都是同一套机制的封装。

三、与 React Query / TanStack Query 的配合

实际项目里你不会自己写 createResource,而是用 React Query 的 Suspense 模式。关键 API 是 useSuspenseQuery(注意:useQuery({ suspense: true }) 那套老配置已经被拆成独立 hook 了):

import { useSuspenseQuery } from '@tanstack/react-query';

function ArticleList() {
  const { data } = useSuspenseQuery({
    queryKey: ['articles'],
    queryFn: fetchArticles,
  });

  // 注意:data 这里一定是有的,不再需要判空和 isLoading
  return <ul>{data.map((a) => <li key={a.id}>{a.title}</li>)}</ul>;
}

useSuspenseQuery 不再返回 isLoading / isError,因为它的契约是:要么给你数据,要么挂起。loading 由外层 Suspense 兜,error 由外层 Error Boundary 兜(下一节会讲)。这让组件本身的代码变得极其干净——只写"数据已经回来了"的快乐路径。

一个常被忽略的细节:Suspense 在 React Query 里不是并发魔法。如果你在父组件顺序发起多个查询,仍然会串行。真正让它们并发的,是 React 18 引入的"并发特性 + transition"。把数据获取包在 startTransition 里,或在 Server Components 场景下让 React 调度这些挂起,才能避免瀑布。这也是为什么 Suspense 和并发渲染总是成对出现——它是并发特性的消费者。

四、流式 SSR:Server Components + Suspense

Suspense 真正改变游戏规则的地方,是流式 SSR。传统 SSR 是"等所有数据都好了,再返回整个 HTML",首屏白屏时间长。Server Components + Suspense 之后,Next.js(Turbopack / Next 16 已经全面支持)可以:

1. 服务端先流式返回一个 HTML 骨架——已就绪的部分直接渲染,未就绪的部分用 Suspense fallback 占位。
2. 浏览器收到骨架后立刻能渲染,不用等。
3. 慢的部分在服务端数据就绪后,作为流式 chunk 继续推送到浏览器,React 在原地把它"填"进去。

// app/dashboard/page.tsx (Next.js Server Component)
import { Suspense } from 'react';

export default function DashboardPage() {
  return (
    <main>
      <Header />
      <Suspense fallback={<ChartSkeleton />}>
        {/* 这个查询要 800ms,但不会阻塞首屏 */}
        <RevenueChart />
      </Suspense>
      <Suspense fallback={<ListSkeleton />}>
        <RecentOrders />
      </Suspense>
    </main>
  );
}

这里的心理模型要换一下:在 Server Components 里,"组件渲染"本身就是一次数据获取过程——async 组件 await 数据库查询,React 把这次 await 当成 Suspense 的挂起点。你不需要写 useQuery,Suspense 是框架原生提供的。这意味着 TTFB(Time To First Byte)可以做到极低,而最慢的那个数据块决定的是"它自己区域"的填充时间,不再是整个页面的首屏时间。

一个实战要点:流式 SSR 下,loading.tsx(Next.js 的约定)本质上就是一个 Suspense 边界。你每加一个 loading.tsx,就等于在那段路由子树上包了一层 Suspense。

五、Suspense 边界策略:粒度是个技术活

新手上路最容易犯的两个错,都和边界粒度有关。

错误一:每个组件都包一层 Suspense。 看起来很"模块化",实际上每个组件独立挂起、独立恢复,页面会出现一堆 fallback 同时跳动,然后此起彼伏地消失,体验极差。而且 fallback 之间没有协调,视觉上像在抽搐。

错误二:整个页面只包一层 Suspense。 等于退化成"全有或全无"——任何一个子查询慢,整个页面都白屏等它。流式 SSR 的优势被浪费。

正确的做法是按"内容块"划分边界。问自己:这块内容在视觉上、语义上是不是一个独立的单元?用户能不能接受"这一块晚一点出现"?如果是,它就是一个独立的 Suspense 单元。

经验法则:

• 顶部导航、面包屑这种"页面框架"——别包,或包成最外层骨架,首屏就要在。
• 主内容区(文章正文、列表)——独立包,慢就慢,先给骨架。
• 次要内容(评论区、推荐栏、侧栏)——独立包,可以晚到。
• 一个列表内部的每一项——千万别包,粒度太细。

六、和 Error Boundary 配合:覆盖异步生命周期

Suspense 只管 loading,不管 error。一个挂起的 promise 如果 reject 了,它会向上冒泡成一个 JS 错误——这时候接住它的是 Error Boundary。所以一个完整的异步组件生命周期,需要两个边界协同:

import { Suspense } from 'react';
import { ErrorBoundary } from 'react-error-boundary';

function AsyncBlock() {
  return (
    <ErrorBoundary fallback={<ErrorFallback />}>
      <Suspense fallback={<Skeleton />}>
        <ArticleList />
      </Suspense>
    </ErrorBoundary>
  );
}

它们的分工很清晰:

• Suspense 管 loading:子树挂起时,展示 fallback。
• Error Boundary 管 error:子树(含挂起的 promise)抛错时,展示 error UI。

一个常被忽略的坑:Error Boundary 必须在 Suspense 外层。如果反过来包,错误会先被 Suspense 当成"未就绪"处理,行为不可预期。记住顺序——Error Boundary 在外,Suspense 在内,组件在最里,这是异步组件的标准三明治结构。

另外,请求失败后想重试,记得用 resetKey 或在 Error Boundary 上传一个 key 来强制重挂载,否则 React 不会自动清除错误状态。

七、Suspense 不是万能:认清它的适用边界

Suspense 适合的是渲染期数据依赖——也就是"组件一渲染就需要这个数据,数据没来就没法画"。列表、详情、仪表盘这种,天生适合。

但它不适合命令式异步,尤其是事件触发的请求:点击"保存"提交表单、点击"搜索"发起查询、失焦时校验。这些场景的特点是,请求的发起时机和"组件渲染"无关,而且你通常需要拿到结果后做后续操作(跳转、提示、更新别的状态)。强行用 Suspense 去接,会出现"点击后组件突然挂起、fallback 闪一下又回来"的诡异交互。

这类场景,继续用 useMutation / 普通 useQuery + 手动 loading 就好。Suspense 不是要取代所有 loading 状态,它取代的是"渲染期同步依赖异步值"这一类。

判断标准很简单:这个异步值,是不是组件能正常渲染的前提? 是 → 适合 Suspense;不是,而是某个用户动作的结果 → 用命令式。把这两类分开,你就不会误用。

小结

• Suspense 是协议,不是数据获取库。 它只规定"挂起 = throw promise",React Query、SWR、Server Components 都是这个协议的实现。
• 声明式取代命令式。 useSuspenseQuery 不再返回 isLoading,组件只写快乐路径,loading 交给外层边界。
• 流式 SSR 是 Suspense 最大的价值放大器。 Server Components + Suspense 让首屏只等最慢的"那一块",而不是整个页面。Next.js 的 loading.tsx 本质就是 Suspense 边界。
• 边界粒度按内容块划分。 太细=视觉抽搐,太粗=退化成白屏。框架/主内容/次要内容,分层来。
• Error Boundary 在外,Suspense 在内。 两者协同覆盖异步组件的完整生命周期,顺序别反。

金句: Suspense 治好的不是"数据获取",而是"组件和异步值之间那段永远写不好的胶水代码——它让'等数据'回归声明式,让 loading 重新成为组件树的形状,而不是状态机的地狱。