Redwood Cells 深度指南:声明式 GraphQL 数据获取的生命周期管理

原创2026-09-21 20:43:201,616 阅读
文章标签:后端前端Web框架开发工具

Redwood Cells 深度指南:声明式 GraphQL 数据获取的生命周期管理

导读

Cells 是 Redwood 框架最具标志性的抽象之一:它以纯声明的方式处理 GraphQL 数据获取,你只需要导出几个命名常量来描述查询的各个阶段,框架便会在构建期通过 Babel 插件把这些常量自动装配成一个完整的组件。本文基于 Redwood 官方文档(docs/versioned_docs/version-2.x/cells.md)并结合仓库源码,系统讲解 Cells 的生成方式、七个导出常量的语义与用法、生命周期钩子的底层原理,以及框架如何识别与装配一个 Cell,帮助你在实际项目中写出健壮、可维护的声明式数据获取代码。

什么是 Cells:声明式数据获取

Cells 是 Redwood 对数据获取的声明式抽象。通过为数据获取过程提供约定(conventions),Redwood 可以在"请求发出之前"和"响应返回之后"之间介入,实现查询优化等能力,而你完全不需要改动业务代码。

虽然看起来充满"魔法",但一个 Cell 的本质非常简单——它只是执行一个 GraphQL 查询,并管理这个查询的生命周期。其工作方式是:你导出若干命名的常量,声明你在查询生命周期的各个阶段希望 UI 长什么样;在构建期,一个 Babel 插件会把这些常量组装成一个组件模板(由 createCell 高阶组件驱动),整个过程你不需要编写一行命令式代码。

从源码结构看,这一"组装"过程在 babel-plugin-redwood-cell.ts 中实现:插件会在文件顶部注入 import { createCell } from '@redwoodjs/web',并在文件底部追加 export default createCell({ QUERY, Loading, Success, ... }) 这样的默认导出(见 babel-plugin-redwood-cell.ts)。而真正的运行时逻辑集中在 createCell.tsx 中,它接收这些导出并返回一个真实的 React 组件。

生成一个 Cell

使用 Redwood 的 Cell 生成器可以快速创建一个 Cell:

yarn rw generate cell <name>

该命令会在 web/src/components 下创建名为 <name>Cell 的目录,包含四个文件。执行 yarn rw generate cell user 时输出类似:

~/redwood-app$ yarn rw generate cell user
yarn run v1.22.4
$ /redwood-app/node_modules/.bin/rw g cell user
  ✔ Generating cell files...
    ✔ Writing `./web/src/components/UserCell/UserCell.mock.js`...
    ✔ Writing `./web/src/components/UserCell/UserCell.stories.js`...
    ✔ Writing `./web/src/components/UserCell/UserCell.test.js`...
    ✔ Writing `./web/src/components/UserCell/UserCell.js`...
Done in 1.07s.

四个文件的职责如下表:

文件 说明
<name>Cell.js 真正的 Cell 本体,包含 QUERY、Loading、Empty、Failure、Success 等导出
<name>Cell.test.js 针对 Cell 每个状态(Loading / Empty / Failure / Success)的 Jest 测试
<name>Cell.stories.js 针对 Cell 每个状态的 Storybook stories
<name>Cell.mock.js 供 Jest 测试和 Storybook stories 共用的 mock 数据

生成器源码位于 packages/cli/src/commands/generate/cell,其中 cell.tsx.template 与 cellList.tsx.template 分别是单条数据与列表数据的初始模板。以单条数据模板为例,生成的 QUERY 会基于 schema.prisma 中的模型自动构造,例如 query FindUser($id: Int!) { user: user(id: $id) { id } },并预置了四个状态组件(见 cell.tsx.template)。

单条数据 Cell 与列表 Cell

有时你需要渲染单个条目的 Cell,有时需要渲染列表的 Cell。Redwood 的生成器两者都支持:

  • 首先,生成器会检测 <name> 是单数还是复数。例如要生成渲染用户列表的 Cell,运行 yarn rw generate cell users。
  • 其次,对于单复数同形的不规则单词(如 equipment、pokemon),可以通过 --list 标志显式告诉 Redwood 生成列表 Cell:
yarn rw generate cell equipment --list

Cells 深入:文件中的五个核心导出

生成的四个文件中,只有后缀为 .js 的文件(如上例的 UserCell.js)承载 Cell 的全部逻辑。

该文件一开始会导出五个常量:QUERY、Loading、Empty、Failure 和 Success。QUERY 中的根查询默认与 <name> 同名,这样如果你是基于 schema.prisma 中的模型生成 Cell,就能立刻从数据库取到数据。但很多时候你需要自行修改根查询——例如教程中的示例(参见 tutorial/chapter2/cells.md 中 "Our first cell" 一节)。

使用 Cells:七个可用的导出

一个 Cell 总共可以导出七个东西:

名称 类型 说明
QUERY string | function 要执行的查询
beforeQuery function 生命周期钩子;为查询准备变量(variables)和选项(options)
isEmpty function 生命周期钩子;决定 Cell 是否应渲染 Empty
afterQuery function 生命周期钩子;净化查询返回的数据
Loading component 请求进行中时渲染的组件
Empty component 没有数据(null 或 [])时渲染的组件
Failure component 出错时渲染的组件
Success component 数据加载完成后渲染的组件

其中只有 QUERY 和 Success 是必需的。如果你不导出 Empty,空结果会被交给 Success 处理;如果你不导出 Failure,错误会输出到控制台(在源码层面,若未提供 Failure,createCell.tsx 会直接 throw error)。

除了在正确的时间显示正确的组件,Cells 还会把正确的 props 分发给正确的组件:

  • Loading、Empty、Failure、Success 都能以标准的 React 方式访问从父组件传入的 props,以及 useQuery 返回的大部分字段(作为 queryResult prop 传入);
  • 在此基础上,Empty 和 Success 还额外获得查询返回的 data,以及一个 updating 布尔 prop,用于指示 Cell 当前是否正在获取新数据;
  • Failure 也获得 updating,并且独享 error 和 errorCode 两个 prop。

在 createCell.tsx 的实现中可以看到这些 props 的精确装配逻辑:Failure 收到 error、errorCode(取自 queryResult.errorCode 或 error.graphQLErrors[0].extensions.code)、updating 与 queryResult;Empty / Success 收到 {...props}、{...afterQueryData}、updating 与 queryResult;Loading 则收到 {...props} 与 queryResult。

props 如此之多,难免有命名冲突的风险,需要注意两点:

  • Cell 有一个 prop 与查询返回的根级数据同名:此时根级数据会覆盖你的 prop。但由于 props 同时充当查询变量,你可以从 useQuery 返回的 variables prop 中解构出原始值;或者干脆给 Cell 的 prop 改名。
  • Cell 的 props 或查询结果与 useQuery 的返回字段同名:此时 useQuery 的返回值会覆盖 props 和查询结果。

useQuery 的具体返回内容可以参考 Apollo Client 的 API 文档(error 和 data 经过特殊处理,如上面源码所示)。

QUERY

QUERY 可以是一个字符串(GraphQL document),也可以是一个函数(必须返回合法的 GraphQL document)。使用函数可以让查询更动态。

多根查询是允许的,例如:

export const QUERY = gql`{
  query {
    posts {
      id
      title
    }
    authors {
      id
      name
    }
  }
}

此时 posts 和 authors 都会出现在 Success 中:

export const Success = ({ posts, authors }) => {
  // 用 posts 和 authors 编写渲染逻辑
}

关于变量:Cells 会把从父组件收到的任何 props 作为变量使用(这一点在 beforeQuery 中配置)。例如,BlogPostsCell 接收一个 numberToShow prop,于是 numberToShow 可以直接在 QUERY 中使用:

import BlogPostsCell from 'src/components/BlogPostsCell'

const HomePage = () => {
  return (
    <div>
      <h1>Home</h1>
      <BlogPostsCell numberToShow={3} />
    </div>
  )
}

export default HomePage
export const QUERY = gql`
  query($numberToShow: Int!) {
    posts(numberToShow: $numberToShow) {
      id
      title
    }
  }
`

这意味着你可以从 SDL 反向推导 Cell 的 props:SDL 里有哪些变量,Cell 的 props 就应该是哪些。当 QUERY 是函数时,createCell.tsx 中会用 beforeQuery 的结果作为参数调用它:const query = typeof QUERY === 'function' ? QUERY(options) : QUERY。

beforeQuery

beforeQuery 是一个生命周期钩子,可以把它理解为配置 Apollo Client useQuery 钩子(或旧版 Query 组件)的入口。

默认的 beforeQuery 会把父组件传入的任何 props 交给 QUERY 作为变量,同时将 fetch policy 设为 'cache-and-network'——这是 Redwood 认为大多数场景下最符合用户预期的行为:

export const beforeQuery = (props) => {
  return {
    variables: props,
    fetchPolicy: 'cache-and-network'
   }
}

例如,如果你想开启 Apollo 的轮询(polling)并禁止缓存,可以这样导出:

export const beforeQuery = (props) => {
  return { variables: props, fetchPolicy: 'no-cache', pollInterval: 2500 }
}

beforeQuery 还可以用来注入 Cell props 之外的数据(例如来自 React Context 或全局状态管理库的数据)。一旦提供了 beforeQuery 函数,Cell 的 props 类型会自动与函数第一个参数的类型保持一致:

// 该 Cell 不接受任何 props:<Cell />
export const beforeQuery = () => {
  const { currentUser } = useAuth()

  return {
    variables: { userId: currentUser.id },
  }
}
// 该 Cell 接收一个名为 word 的 string 类型 prop:<Cell word="abc">
export const beforeQuery = ({ word }: { word: string }) => {
  return {
    variables: { magicWord: word }
   }
}

这一设计在类型层面由 cellTypes.ts 中的 CellPropsVariables 类型保证:如果 Cell 存在 beforeQuery,则其 props 类型取 beforeQuery 第一个参数的类型;否则取 GQL 变量类型。

isEmpty

isEmpty 是一个可选的生命周期钩子,返回一个布尔值,指示 Cell 是否应渲染 Empty。用它来覆盖默认的空值检查(默认检查根字段是否为 null 或空数组)。

它接收两个参数:1) data;2) 一个包含默认 isEmpty 函数(名为 isDataEmpty)的对象,因此可以基于默认检查扩展自定义逻辑:

export const isEmpty = (data, { isDataEmpty }) => {
  return isDataEmpty(data) || data?.blog?.status === 'hidden'
}

afterQuery

afterQuery 是一个生命周期钩子,在数据到达 Success 之前运行。用它来净化 QUERY 返回的数据。默认实现原样返回数据:

export const afterQuery = (data) => ({...data})

在 createCell.tsx 中,afterQuery 的输出会通过展开运算符传入 Empty 与 Success:const afterQueryData = afterQuery(data),然后 <Success {...props} {...afterQueryData} ... />。

Loading

如果没有缓存数据且请求正在进行中,Cell 会渲染 Loading。

本地开发时,你可以在浏览器开发者工具 Inspector 的 Network 选项卡把网速调成 "Slow 3G",就能捕捉到 Cell 等待响应的瞬间。但更推荐的方式是使用 Redwood 自带的 Storybook——在 Storybook 中开发 Loading(以及 Failure)组件会轻松得多,不需要 Slow 3G 这类变通手段,也不需要故意弄坏应用来开发组件。

Empty

当没有数据时,Cell 渲染 Empty。

"没有数据"指的是响应为 1) null 或 2) 空数组(<a href="https://link.gitcode.com/i/3e87f0c0a2f0a03fc0aebf8930835368" target="_blank">])。在仓库中,默认的空值判断实现在 [isCellEmpty.ts:

export function isDataEmpty(data?: DataObject) {
  return (
    !data ||
    Object.values(data).every((fieldValue) => {
      return fieldValue === null || isFieldEmptyArray(fieldValue)
    })
  )
}

function isFieldEmptyArray(field: unknown) {
  return Array.isArray(field) && field.length === 0
}

与文档中 2.x 时期展示的内联实现相比,当前实现使用 Object.values(data).every(...) 检查所有根字段,而非仅第一个字段(data<a href="https://link.gitcode.com/i/2bf5061fb0ce905a5633b66924426530" target="_blank">Object.keys(data)[0]]),这是一个值得注意的演进细节。类型注释([isCellEmpty.ts)还特别提醒:如果 SDL 中声明为 posts: [Post!],列表查询同样可能返回 null。

Failure

当查询出错时,Cell 渲染 Failure。想快速看到这个状态很容易——只要在 QUERY 中加一个不存在的字段:

const QUERY = gql`
  query {
    posts {
      id
      title
      nonsense
    }
  }
`

与 Loading 一样,Storybook 是开发 Failure 的更合适场所。

下面这个例子使用 errorCode 条件渲染错误标题,并将其用于国际化翻译字符串:

export const Failure = ({ error, errorCode }: CellFailureProps) => {
  const { t } = useTranslation()
  return (
    <div style={{ color: 'red' }}>
      {errorCode === 'NO_CONFIG' ? <h1>NO_CONFIG</h1> : <h1>ERROR</h1>}
      Error: {error.message} - Code: {errorCode} - {t(`error.${errorCode}`)}
    </div>
  )
}

errorCode 的类型定义见 cellTypes.ts 中的 CellFailureProps,其运行时取值逻辑在 createCell.tsx:优先取 queryResult.errorCode,否则回退到 error.graphQLErrors?.[0]?.extensions?.['code'](对应 Apollo Server 的错误码约定)。

Success

一切顺利时,Cell 渲染 Success。

如前所述,Success 独享 data prop。但如果你尝试从 props 中解构它,会发现它并不存在——因为 Redwood 增加了一层便利:在 createCell.tsx 中,Redwood 用展开运算符(...)把 afterQuery 处理后的 data 展开进了 Success,因此你可以直接从 QUERY 期望的数据解构。

所以,如果你查询 posts 和 authors,不需要这样写:

export const Success = ({ data }) => {
  const { posts, authors } = data

  // 用 posts 和 authors 编写渲染逻辑
  ...
}

Redwood 让你直接这样写:

export const Success = ({ posts, authors }) => {
  // 用 posts 和 authors 编写渲染逻辑
  ...
}

注意你仍然可以给 Success 传任何其他 props——毕竟它说到底只是一个 React 组件。

什么时候应该用 Cell?

只要你需要获取数据,就可以用 Cell——让 Redwood 来管理不同时刻该显示什么,你只需专注于这些界面应该长什么样。

但请记住,你不一定非要用 Cell。例如,对于一次性查询,总可以使用 useApolloClient 钩子拿到客户端对象,然后手动执行查询:

// 在某个 React 组件中...

client = useApolloClient()

client.query({
  query: gql`
    ...
  `
})

可以在 Cell 中执行 Mutation 吗?

当然可以。Redwood 的示例 todo 应用就在 TodoListCell 中执行了 mutation(见示例 web/src/components/TodoListCell/TodoListCell.js 中的相关代码)。Redwood 团队也不认为在 Cell 中执行 mutation 是反模式——恰恰相反,你的 Cell 可能会包含大量逻辑,在很多方面成为应用的枢纽。

同时要记住:除了"导出某些特定名字的东西"之外,Cells 的规则很少——常规组件里能做的一切,在 Cell 里依然可以做。

Redwood 如何识别一个 Cell?

基本规则是:文件名以 "Cell" 结尾即可(所以如果你的组件要成为 Cell,文件名必须以 "Cell" 结尾)。但还有一条补充规则:

Redwood 会查找所有以 "Cell" 结尾的文件,但如果该文件 1) 没有导出名为 QUERY 的常量,并且 2) 有默认导出,那么它会被跳过,不会被当作 Cell 处理。

什么时候会用到这种写法?如果你只是出于某种原因想让文件名以 "Cell" 结尾(比如它其实是一个普通组件)。除此之外,不用操心。

从源码看,这一判断实现在 babel-plugin-redwood-cell.ts 的 Program.exit 中:插件遍历文件中的命名导出,收集 EXPECTED_EXPORTS_FROM_CELL(beforeQuery、QUERY、data、isEmpty、afterQuery、Loading、Success、Failure、Empty)中出现的名字;如果文件已有默认导出(hasDefaultExport),或既没有 QUERY 也没有 data 导出,则直接跳过装配。反之,若导出的是 data(而非 QUERY),插件会改用 createServerCell 并将导入源指向 @redwoodjs/web/dist/components/cell/createServerCell——这是当前仓库中对服务端 Cell(RSC)的扩展支持。

进阶示例:自己实现一个 Cell

假设没有 Babel 在构建期替我们组装导出,你会如何自己实现一个 Cell?

先看教程中获取 posts 的例子(见 tutorial/chapter2/cells.md):

export const QUERY = gql`
  query {
    posts {
      id
      title
      body
      createdAt
    }
  }
`

export const Loading = () => <div>Loading...</div>

export const Empty = () => <div>No posts yet!</div>

export const Failure = ({ error }) => (
  <div>Error loading posts: {error.message}</div>
)

export const Success = ({ posts }) => {
  return posts.map((post) => (
    <article>
      <h2>{post.title}</h2>
      <div>{post.body}</div>
    </article>
  ))
}

如果 Babel 不来替我们组装这些导出,我们大概会写出这样的代码:

const QUERY = gql`
  query {
    posts {
      id
      title
      body
      createdAt
    }
  }
`

const Loading = () => <div>Loading...</div>

const Empty = () => <div>No posts yet!</div>

const Failure = ({ error }) => (
  <div>Error loading posts: {error.message}</div>
)

const Success = ({ posts }) => {
  return posts.map((post) => (
    <article>
      <h2>{post.title}</h2>
      <div>{post.body}</div>
    </article>
  ))
}

const isEmpty = (data) => {
  return isDataNull(data) || isDataEmptyArray(data)
}

export const Cell = () => {
  return (
    <Query query={QUERY}>
      {({ error, loading, data }) => {
        if (error) {
          if (Failure) {
            return <Failure error={error} />
          } else {
            console.error(error)
          }
        } else if (loading) {
          return <Loading />
        } else if (data) {
          if (typeof Empty !== 'undefined' && isEmpty(data)) {
            return <Empty />
          } else {
            return <Success {...data} />
          }
        } else {
          throw 'Cannot render Cell: graphQL success but `data` is null'
        }
      }}
    </Query>
  )
}

这是一大段代码,而且全是命令式代码——这基本就是把 createCell.tsx 的内容手抄进文件里。想象一下,每次要获取可能延迟响应的数据都得这么写?太可怕了。这正是 Cells 存在的意义:用约定替代样板代码,用声明替代命令。

深入源码:createCell 的运行时装配逻辑

如果想要更精确地理解 Cells 的运行时行为,可以阅读 createCell.tsx 的关键分支:

  • 默认 beforeQuery:源码中的默认实现(createCell.tsx)将 props 作为变量,并设置 fetchPolicy: 'cache-and-network' 与 notifyOnNetworkStatusChange: true(后者是文档未提及但对 updating prop 至关重要的配置,它让组件在轮询/重取数据时收到状态更新)。
  • 状态分发:error → Failure(未定义则 throw);data 存在 → 先过 afterQuery,再经 isEmpty 判断渲染 Empty 或 Success;否则 loading → Loading;最后还有一个兜底的 else 分支(createCell.tsx),抛出 "Cannot render Cell: reached an unexpected state..." 错误并提示可能由 GraphQL 缓存问题导致、建议为查询字段补充 id。
  • 预渲染(Prerender)支持:在 globalThis.__REDWOOD__PRERENDERING 为真时,Cell 会与 CellCacheContext 协作完成预渲染缓存(createCell.tsx),并以操作名加序列化变量生成缓存键;若查询缺少操作名(operation name),会直接抛错提示补充类似 query FindBlogPostQuery($id: Int!) 的命名。
  • 客户端切换:createCell 导出本身是一个运行时开关——当启用流式 SSR(RWJS_ENV.RWJS_EXP_STREAMING_SSR)时切换到 createSuspendingCell(createCell.tsx),对应实现位于 createSuspendingCell.tsx。

结语

Cells 把 GraphQL 查询的生命周期浓缩成几个命名导出,让数据获取回归"声明式"的本质。理解 QUERY、beforeQuery、isEmpty、afterQuery、Loading、Empty、Failure、Success 这七个导出各自的职责与 props 分发规则,再对照 createCell.tsx、isCellEmpty.ts、babel-plugin-redwood-cell.ts 等源码,你就能在项目中熟练运用这一抽象,甚至在需要时自己动手定制。更多相关主题可继续阅读 tutorial/chapter2/cells.md(教程实战)与 typescript/utility-types.md(Cells 相关的 TypeScript 工具类型)。

登录后查看全文
redwood