Redwood Cells 完全指南:声明式数据获取与查询生命周期管理

原创2026-09-22 16:31:491,668 阅读
文章标签:后端前端Web框架开发工具

Redwood Cells 完全指南:声明式数据获取与查询生命周期管理

Cells 是 Redwood 框架最具标志性的抽象之一,它以声明式方式封装 GraphQL 数据获取,让你只关注 UI 在查询各阶段"长什么样",而把"何时渲染什么"交给框架处理。本文将基于 v6.x 文档与仓库源码(babel-plugin-redwood-cell.ts、createCell.tsx 等)深入讲解 Cell 的生成、七个导出、生命周期钩子、Babel 装配原理,以及如何手动实现一个 Cell。

什么是 Cells

Cells 是 Redwood 中对数据获取的一种声明式处理方式,也是框架的标志性抽象之一。通过围绕数据获取建立约定,Redwood 可以在"请求"与"响应"之间插入能力,例如查询优化,而这一切都无需你修改任何业务代码。

听起来似乎充满魔法,但一个 Cell 本质上只做两件事:执行一个 GraphQL 查询,并管理这个查询的生命周期。其核心思路是:你导出一些命名常量,声明你在查询生命周期各个阶段希望 UI 呈现的样子;Redwood 在构建期通过一个 Babel 插件(babel-plugin-redwood-cell)把这些导出组装成一个组件模板。全程你都不需要写一行命令式代码。

文档原文对这一点描述得很直接:"While it might seem like there's a lot of magic involved, all a Cell really does is execute a GraphQL query and manage its lifecycle."

生成一个 Cell

使用 Redwood 的 Cell 生成器即可:

yarn rw generate cell <name>

该命令会在 web/src/components 下创建一个名为 <name>Cell 的目录,包含四个文件:

文件 说明
<name>Cell.js 真正的 Cell(TypeScript 项目为 .jsx/.tsx)
<name>Cell.test.js 覆盖 Cell 各状态的 Jest 测试
<name>Cell.stories.js 覆盖 Cell 各状态的 Storybook stories
<name>Cell.mock.js 同时服务于 Jest 测试与 Storybook stories 的 mock 数据

这四个文件的生成逻辑可以在 cell.js 中看到:templateForComponentFile 被调用四次,分别产出 Cell 本体、测试、stories 与 mock 文件。其中 Cell 本体由 cell.tsx.template(单条)或 cellList.tsx.template(列表)渲染而成。

以 TypeScript 单条 Cell 为例,生成器会从 schema.prisma 中推断模型的 id 字段名与类型,生成形如下面的骨架:

import type { ${operationName}, ${operationName}Variables } from 'types/graphql'

import type {
  CellSuccessProps,
  CellFailureProps,
  TypedDocumentNode,
} from '@redwoodjs/web'

export const QUERY: TypedDocumentNode<...> = gql`
  query ${operationName}($id: ${idType}!) {
    ${camelName}: ${camelName}(${idName}: $id) {
      ${idName}
    }
  }
`

export const Loading = () => <div>Loading...</div>
export const Empty = () => <div>Empty</div>
export const Failure = ({ error }: CellFailureProps<...>) => (
  <div style={{ color: 'red' }}>Error: {error?.message}</div>
)
export const Success = ({ ${camelName} }: CellSuccessProps<...>) => {
  return <div>{JSON.stringify(${camelName})}</div>
}

单条 Cell vs 列表 Cell

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

首先,它检测 <name> 是单数还是复数。例如要生成渲染用户列表的 Cell,直接运行 yarn rw generate cell users。

其次,对于单复数同形的不规则词(如 "equipment"、"pokemon"),你可以显式传入 --list 告诉 Redwood 生成列表 Cell:

yarn rw generate cell equipment --list

这一逻辑在 cell.js 中由 isWordPluralizable 与 isPlural 判断,若单词不可复数化(单复同形)则回落到 options.list:

const shouldGenerateList =
  (isWordPluralizable(cellName) ? isPlural(cellName) : options.list) ||
  options.list

生成列表 Cell 时,templateNameSuffix 会被设为 'List',从而改用 cellList.tsx.template,并强制把名字复数化(forcePluralizeWord)。另外还可以用 --query 指定自定义的 operation name(cell.js 中会先检查该名称是否唯一,不唯一会直接抛错)。

Cells 深入

一个 Cell 导出五个常量:QUERY、Loading、Empty、Failure 和 Success。QUERY 中的根查询名默认与 <name> 相同——如果你是基于 schema.prisma 中的模型生成 Cell,那么立刻就能从数据库取到数据。但很可能你不会以这种方式生成 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,错误会直接输出到控制台。

这一约定在 Babel 插件的源码中得到了印证:babel-plugin-redwood-cell.ts 里维护了一个 EXPECTED_EXPORTS_FROM_CELL 数组:

const EXPECTED_EXPORTS_FROM_CELL = [
  'beforeQuery',
  'QUERY',
  'data',
  'isEmpty',
  'afterQuery',
  'Loading',
  'Success',
  'Failure',
  'Empty',
]

props 的分发

除了在正确的时间显示正确的组件,Cells 还会把正确的 props 传递给正确的组件。Loading、Empty、Failure、Success 都能以常规 React 方式访问从 Cell 传下来的 props,并且都能拿到 useQuery hook 返回值的大部分内容(作为一个名为 queryResult 的 prop)。除此之外:

  • Empty 与 Success 额外拿到查询返回的 data,以及一个 updating prop,用于表示 Cell 当前是否正在获取新数据;
  • Failure 额外拿到 updating,并且独占 error 与 errorCode。

上文说 Cells 拿到 useQuery 返回值的"大部分"——你可以在 Apollo Client 的 API 参考中查看 useQuery 到底返回什么。再次强调:error 和 data 被特殊处理了。

这一分发逻辑的落地实现就在 createCell.tsx 中:错误时向 Failure 传入 error、errorCode、updating 与 queryResult;成功时向 Empty/Success 展开传入 props、afterQuery(data) 结果、updating 与 queryResult。其中 errorCode 在源码里是这样解析的:

errorCode={
  (queryResult as QueryResultWithErrorCode).errorCode ??
  (error.graphQLErrors?.[0]?.extensions?.['code'] as string)
}

也就是说,errorCode 优先取 queryResult 中已有的值,否则从 GraphQL 错误的 extensions.code 中提取——这正好对应用户自定义指令(如 @requireAuth)或 Apollo Server 错误码。

QUERY

QUERY 可以是一个字符串,也可以是一个函数。如果是函数,它必须返回一个合法的 GraphQL document。

一个 Cell 里有多个根查询完全没问题,例如:

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

这种情况下,posts 和 authors 都会传给 Success:

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

通常查询会带变量。Cells 默认把从父组件接收到的任何 props 都当作变量(这个设置在 beforeQuery 里完成)。例如这里的 BlogPostCell 接收一个 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 里有哪些 variables,Cell 的 props 就应该是什么。

在 createCell.tsx 中可以看到 QUERY 的函数形态是如何被处理的:

const options = beforeQuery(variables as CellProps)
const query = typeof QUERY === 'function' ? QUERY(options) : QUERY

也就是说,当 QUERY 是函数时,它接收 beforeQuery 的返回值作为参数,并据此返回最终要执行的查询。

beforeQuery

beforeQuery 是一个生命周期钩子。最好的理解方式:它是配置 Apollo Client useQuery 钩子的机会。

默认情况下,beforeQuery 会把父组件传下来的所有 props 交给 QUERY,使它们成为查询变量;同时把 fetch policy 设为 'cache-and-network',因为官方认为这最符合大多数用户期望的行为:

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

例如,如果你想开启 Apollo 的轮询并禁用缓存,可以导出类似这样的实现(详见 Apollo 关于 polling 与 fetch policy 的文档):

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

你也可以用 beforeQuery 用 Cell props 之外的数据填充变量(例如来自 React Context API 或全局状态管理库的数据)。一旦你提供了 beforeQuery 函数,Cell 会自动把自身 props 的类型改为该函数第一个参数的类型:

// The Cell will take no props: <Cell />
export const beforeQuery = () => {
  const { currentUser } = useAuth()

  return {
    variables: { userId: currentUser.id }
   }
}
// The cell will take 1 prop named "word" that is a string: <Cell word="abc">
export const beforeQuery = ({ word }: { word: string }) => {
  return {
    variables: { magicWord: word }
   }
}

默认实现可以直接在 createCell.tsx 里看到——它就是 createNonSuspendingCell 的参数默认值:

beforeQuery = (props) => ({
  // By default, we assume that the props are the gql-variables.
  variables: props as unknown as CellVariables,
  fetchPolicy: 'cache-and-network',
  notifyOnNetworkStatusChange: true,
})

注意源码还额外设置了 notifyOnNetworkStatusChange: true,并且注释提到:由于 Apollo Client v3.5.4 的一个疑似 bug(没有遵守 RedwoodApolloProvider 中的 defaultOptions),这里把这些默认值重复了一遍。这也是 updating prop 能随网络状态变化而更新的关键。

isEmpty

isEmpty 是一个可选的生命周期钩子,返回一个布尔值表示 Cell 是否应该渲染空状态。用它来覆盖默认检查——默认检查会判断 Cell 的根字段是否为 null 或空数组。

它接收两个参数:1) data,2) 一个包含默认 isEmpty 函数的对象,默认函数名为 isDataEmpty,这样你可以基于默认行为做扩展:

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

默认的 isDataEmpty 实现在 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
}

注意这里的语义:只有当所有根字段都是 null 或空数组时,才判定为空。假如你的查询同时返回 posts: [] 和 authors: [ ... ],默认的 isEmpty 会返回 false,于是走 Success 分支——这正是文档中"多个根查询"场景下需要留意的地方。在 createCell.tsx 中它的调用点是:

if (isEmpty(data, { isDataEmpty }) && Empty) {

即 isEmpty 返回 true 且你导出了 Empty,才会渲染 Empty;否则数据照常进入 Success。

afterQuery

afterQuery 是一个生命周期钩子,运行在数据到达 Success 之前。用它来对 QUERY 返回的数据做清洗(sanitize)。

默认情况下 afterQuery 原样返回数据:

afterQuery = (data) => data,

在 createCell.tsx 中,它的执行顺序在 isEmpty 判断之前:

const afterQueryData = afterQuery(data)

if (isEmpty(data, { isDataEmpty }) && Empty) {
  // render Empty with {...afterQueryData}
} else {
  // render Success with {...afterQueryData}
}

Loading

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

本地开发时,你可以在 DevTools Network 面板把网速调成 "Slow 3G",就能捕捉到 Cell 等待响应的瞬间。

但既然 Redwood 自带 Storybook,何必再用 Slow 3G?Storybook 让开发 Loading(以及 Failure)这样的组件变得轻而易举——你不必再用 Slow 3G 之类的 hack,也不必故意弄坏应用来开发组件。

生成器产出的 Cell 自带 .stories.js 与 .mock.js,就是为此准备的:mock 数据可以覆盖查询的各个状态,Storybook 中即可直接预览。

Empty

如果没有数据,Cell 渲染该组件。这里的"没有数据"指的是响应为:1) null,或 2) 空数组([])。

如前所述,未导出 Empty 时,空数据会直接交给 Success。

Failure

出错时 Cell 渲染该组件。想快速看到效果,可以在你的 QUERY 里加一个未定义类型的字段:

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

但和 Loading 一样,Storybook 更适合用来开发这个组件。

下面的例子中,我们用 errorCode 条件渲染错误标题,同时把它用作翻译字符串的 key:

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>
  )
}

这里使用的 CellFailureProps 类型定义在 cellTypes.ts:

export type CellFailureProps<TVariables extends OperationVariables = any> = {
  queryResult?: NonSuspenseCellQueryResult<TVariables, any> | SuspenseCellQueryResult
  error?: QueryOperationResult['error'] | Error // for tests and storybook
  errorCode?: string
  updating?: boolean
} & InputVarProps<TVariables>

errorCode 为可选字符串,error 类型上兼容了测试与 Storybook 场景(既可能是 Apollo 的查询错误对象,也可能只是一个 Error)。

Success

如果一切顺利,Cell 渲染 Success。

如前所述,Success 独占访问 data prop。但如果你试图从 props 中解构它,会发现它并不存在——这是因为 Redwood 加了一层便利:Redwood 会把 data 展开(spread)进 Success,这样你可以直接从 QUERY 期望的数据中解构。

所以,如果你查询的是 posts 和 authors,与其这样写:

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

  // ...
}

Redwood 让你直接这样写:

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

注意你仍然可以向 Success 传任何其他 props——毕竟它只是一个普通的 React 组件。

:::tip 想了解 TypeScript 如何与 Cells 协作?请看 Utility Types 文档。 :::

什么时候该用 Cell?

只要你想获取数据,就可以用 Cell。让 Redwood 去统筹"什么时候显示什么",你只需专注于这些状态长什么样。

但有一点很重要:你不一定非要用 Cell。你想怎么做都可以!例如,一次性查询可以随时使用 useApolloClient。这个 hook 返回 client,你可以用它执行查询等操作:

// In a react component...

client = useApolloClient()

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

可以在 Cell 里执行 Mutation 吗?

完全可以。我们在 TodoListCell 中就是这样做的。官方也不认为这是反模式——恰恰相反,你的 Cell 最终可能包含大量逻辑,在很多时候真正成为应用的"中枢"。

另外要记住:除了"导出某些特定名称"之外,Cells 几乎没有其他规则——你在普通组件里能做的一切,在 Cell 里依然成立。

Redwood 怎么知道一个 Cell 是 Cell?

只要文件名以 "Cell" 结尾就行?基本正确,但还有一点要知道。

Redwood 会查找所有以 "Cell" 结尾的文件(所以如果你的组件想成为 Cell,文件名确实必须以 "Cell" 结尾),但如果该文件 1) 没有导出名为 QUERY 的常量,且 2) 有默认导出,那么它会被跳过。

什么时候需要这样?比如你只是出于某种原因想让文件名以 "Cell" 结尾。除此之外,不用操心这个规则。

源码印证:Babel 插件的判定逻辑

这一判定规则在 babel-plugin-redwood-cell.ts 中实现得明明白白。插件会遍历文件的命名导出,收集 EXPECTED_EXPORTS_FROM_CELL 中出现的名字;在 Program 退出时执行判定:

const hasQueryOrDataExport =
  exportNames.includes('QUERY') || exportNames.includes('data')

// 如果文件已有默认导出,或没有 QUERY/data 导出,就不是合法 Cell,直接跳过
if (hasDefaultExport || !hasQueryOrDataExport) {
  return
}

这正好对应文档描述的两条规则:有默认导出(很可能已经被 createCell 包装过,或根本不是 Cell)或没有 QUERY 导出,都会被跳过。

通过判定后,插件会做两件事(这就是"构建期装配"的本质):

  1. 在文件顶部插入导入语句:import { createCell } from '@redwoodjs/web';
  2. 在文件底部追加默认导出:export default createCell({ QUERY, Loading, Success, Failure, Empty, beforeQuery, isEmpty, afterQuery, displayName })。

其中 displayName 取自文件名,便于在 React DevTools 中识别。完整逻辑见 babel-plugin-redwood-cell.ts 的 Program.exit 部分,插件测试见 babel-plugin-redwood-cell.test.ts。

运行期:createCell 到底做了什么

经过 Babel 装配后,运行时真正干活的是 createCell.tsx。它接收 QUERY 与各生命周期组件,返回一个普通的 React 组件 NamedCell,其核心流程为:

  1. 剥离 children(Cells 不渲染 children),把其余 props 当作候选变量;
  2. 调用 beforeQuery(variables) 得到 options(默认注入 cache-and-network fetch policy);
  3. 若 QUERY 是函数,则 QUERY(options) 求值得到查询;
  4. 调用 useQuery(query, options) 拿到 error、loading、data 与其余 queryResult;
  5. 按优先级分支渲染:error 且存在 Failure → 渲染 Failure(否则抛错);data → 先 afterQuery 再 isEmpty 判断,决定渲染 Empty 或 Success(并展开 afterQueryData);loading → 渲染 Loading;都不满足 → 抛出"查询成功但 data 为 null"的异常并给出排查提示。

此外,createCell 会根据构建环境切换实现:RWJS_ENV.RWJS_EXP_STREAMING_SSR 为真时使用 createSuspendingCell(支持流式 SSR 的 Suspense 版本),否则使用非 Suspense 版本。从源码结构看,Suspense 版本对应 createSuspendingCell.js(与 createCell.tsx 同目录)。

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

假设没有那些构建期魔法,你会如何自己实现一个 Cell?

考虑教程中的例子——获取 posts:

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 存在的意义——把这段"样板命令式逻辑"固化进框架,让每个数据获取场景都变得只有一行声明。

小结

  • Cell 是"一个 GraphQL 查询 + 一套生命周期 UI"的声明式封装,由 Babel 插件在构建期组装,由 createCell.tsx 在运行期执行;
  • 七个导出中只有 QUERY 与 Success 必需,Empty/Failure 缺失时各有降级行为(空数据进 Success、错误输出到控制台);
  • beforeQuery 负责准备变量与 Apollo options(默认 cache-and-network + notifyOnNetworkStatusChange),afterQuery 负责数据清洗,isEmpty 负责覆盖空状态判定(默认实现见 isCellEmpty.ts);
  • props 自动分发:data 被展开进 Success/Empty,error/errorCode 专属 Failure,updating 与 queryResult 各状态可用;
  • 文件以 "Cell" 结尾、导出 QUERY、无默认导出,三者共同决定文件是否被识别为 Cell(判定源码见 babel-plugin-redwood-cell.ts)。

更多实战示例请参考 教程 Cells 章节 与仓库中的示例项目,例如 example-todo-main。

登录后查看全文
redwood