RedwoodJS Cells 深度指南:用声明式约定驾驭 GraphQL 数据获取生命周期

原创2026-09-20 15:13:191,914 阅读
文章标签:后端前端Web框架开发工具

RedwoodJS Cells 深度指南:用声明式约定驾驭 GraphQL 数据获取生命周期

Cells 是 RedwoodJS 最具标志性的抽象模式之一:你只需导出 QUERY、Loading、Empty、Failure、Success 等命名常量,声明"查询生命周期各个阶段长什么样",框架便会借助 Babel 插件在构建期把这些常量自动装配成一个完整的 React 组件。本文以官方文档 docs/docs/cells.md 为主线,结合仓库中 createCell.tsx、babel-plugin-redwood-cell.ts 等源码实现,带你从"会用"深入到"懂原理",掌握 Cell 的全部七个导出、生成器用法、生命周期钩子,以及框架在构建期究竟替你做了什么。

Cells 是什么:一次查询,五种状态,零命令式代码

Cells 是一套声明式的数据获取方案,是 RedwoodJS 最具代表性的抽象模式之一。它通过约定(convention)接管"请求 → 响应"的整个过程,让框架得以在请求与响应之间插入查询优化等能力,而你的应用代码完全无需改动。

表面上看起来充满"魔法",但一个 Cell 的本质非常简单:它只是执行一次 GraphQL 查询并管理其生命周期。核心思想是:你导出若干个命名常量,声明查询生命周期每个阶段 UI 应该长什么样,Redwood 在构建期通过 Babel 插件把这些常量装配成一个组件模板——全程不需要你写一行命令式代码。

例如,一个最基本的 Cell 文件看起来是这样的:

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

这段代码没有 useQuery、没有 loading/error/data 的判断逻辑——框架会处理好一切。

生成一个 Cell:一个命令产出四个文件

使用 Redwood 的 Cell 生成器即可创建 Cell:

yarn rw generate cell <name>

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

文件 说明
<name>Cell.js 真正的 Cell 本体
<name>Cell.test.js 覆盖 Cell 各状态的 Jest 测试
<name>Cell.stories.js 覆盖 Cell 各状态的 Storybook stories
<name>Cell.mock.js 供 Jest 测试与 Storybook stories 共用的 Mock 数据

从生成器源码 cell.js 可以看到,生成器不仅产出这四个文件,还会做大量智能推断:

  • 解析 Prisma 模型:通过 getSchema(pascalcase(singularize(cellName))) 从 schema.prisma 中读取对应模型,进而推断主键字段名(getIdName)与主键类型(getIdType),并据此生成按 id 查询的默认 QUERY(如 post(id: $id))以及 mock 值(默认 [42, 43, 44],String 类型会自动加引号);
  • 生成唯一操作名:通过 uniqueOperationName 确保生成的 query FindXxxQuery 操作名在整个项目中唯一,若你手动用 --query 指定操作名,还会调用 operationNameIsUnique 校验其不与其他已存在的操作名冲突;
  • 选择模板:根据"单条"还是"列表"选择 cell.tsx.template 或 cellList.tsx.template,并分别产出对应的测试、story 与 mock 文件。

单条 Cell vs 列表 Cell:智能推断与 --list 兜底

有时你需要渲染单条数据,有时需要渲染列表,Redwood 的 Cell 生成器两者皆可。

首先,生成器会检测 <name> 是单数还是复数。例如要生成一个渲染用户列表的 Cell,运行 yarn rw generate cell users 即可。

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

yarn rw generate cell equipment --list

在源码层面,这个判断逻辑对应 cell.js 中的 shouldGenerateList:

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

即:单词可复数化时按单词本身的单复数判断;不可复数化(单复同形)时,完全依赖 --list 参数。一旦判定为列表,cellName 会被强制复数化(forcePluralizeWord),模板切换到 cellList.tsx.template,操作名也变为 Find<Plural>s 形式。

Cells 的七个导出:一张表讲清全部契约

使用 Cells 时,你一共有七个导出可用:

名称 类型 说明
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,错误会输出到控制台。

这些契约在类型层面被严格定义在 cellTypes.ts 的 CreateCellProps 接口中,源码注释明确了每个字段的语义:QUERY 是 "The GraphQL syntax tree to execute or function to call that returns it";beforeQuery 是 "Parse props into query variables";afterQuery 是 "Sanitize the data returned from the query"。而在 Babel 插件的 EXPECTED_EXPORTS_FROM_CELL 列表中,允许从 Cell 文件导出的正是这些名称:beforeQuery、QUERY、data、isEmpty、afterQuery、Loading、Success、Failure、Empty(data 是 RSC 服务端 Cell 场景的扩展)。

组件与 Props 的精确分流

除了在正确的时机渲染正确的组件,Cells 还会把正确的 props 精确地传给正确的组件。Loading、Empty、Failure、Success 都能以标准的 React 方式访问父组件传下来的 props,并且都能拿到 useQuery 返回结果的大部分内容(作为名为 queryResult 的 prop)。在此基础上:

  • Empty 和 Success 额外获得查询返回的 data,以及一个 updating 布尔值,表示 Cell 是否正在拉取新数据;
  • Failure 额外获得 updating,并且独占 error 和 errorCode 两个 props。

"useQuery 返回结果的大部分内容"这一说法的精确定义,可以在 createCell.tsx 的源码中看到:框架从 useQuery 的返回值中解构出 error、loading、data 三个字段做生命周期判断,其余全部原样收进 queryResult 透传给各个状态组件。

QUERY:字符串或函数,多个根查询也 OK

QUERY 可以是字符串,也可以是函数(函数必须返回一个合法的 GraphQL document)。在源码 createCell.tsx 中可以看到:如果 QUERY 是函数,它会被以 beforeQuery 的返回结果作为参数调用一次,再执行。

一个 Cell 里含有多个根查询完全没问题:

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

这种情况下,posts 和 authors 都会出现在 Success 的 props 里:

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

props 即 variables:从 SDL 反推 Cell 的 props

通常查询都带有变量。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 里定义了哪些查询变量,Cell 的 props 就应该是什么。类型层面,cellTypes.ts 中的 CellPropsVariables 精确刻画了这一行为:如果 Cell 定义了 beforeQuery,props 类型取自 beforeQuery 的第一个参数;否则直接取 GQLVariables。

beforeQuery:配置 useQuery 的唯一入口

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

默认情况下,beforeQuery 会把父组件传入的任何 props 交给 QUERY 作为 variables,同时把 fetch policy 设置为 'cache-and-network'(框架认为这最符合多数用户期望的行为):

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

这一默认实现与 createCell.tsx 中 createNonSuspendingCell 的默认参数完全一致。值得注意的是,源码注释还揭示了一个细节:默认的 fetchPolicy: 'cache-and-network' 和 notifyOnNetworkStatusChange: true 之所以在 beforeQuery 里重复设置,是因为 Apollo Client v3.5.4 的一个疑似 bug——它没有尊重 RedwoodApolloProvider 中配置的 defaultOptions。

例如,若想开启 Apollo 的轮询并禁用缓存,可以这样写:

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

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

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

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

这正是 cellTypes.ts 中 CellPropsVariables 的条件类型逻辑:有 beforeQuery 时以 Parameters<Cell['beforeQuery']>[0] 为准,没有时以 GQLVariables 为准。

isEmpty:覆盖"什么算空"的默认判断

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

它接收两个参数:1) data;2) 一个包含默认 isEmpty 函数(名为 isDataEmpty)的对象,方便你在默认行为之上做扩展:

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

默认实现位于 isCellEmpty.ts,其逻辑为:data 不存在,或 data 的所有字段值均为 null 或空数组时,视为空:

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

注意两个细节(源码注释与 cellTypes.ts 均有说明):

  • 列表字段的 SDL 声明不同(如 posts: [Post!] vs posts: [Post]),空数据可能返回 [] 也可能返回 null,默认实现两种情况都覆盖;
  • 对于多根查询,默认 isEmpty 只保证"至少有一处数据",并不保证所有字段都有数据——因此 cellTypes.ts 中的 ConditionallyGuaranteed 类型只在单根查询时把数据标记为必然非空。

afterQuery:数据抵达 Success 前的最后一道清洗

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

默认情况下,afterQuery 原样返回数据。在 createCell.tsx 中可以看到它的调用位置与调用方式:const afterQueryData = afterQuery(data),随后这份处理后的数据会被展开(spread)进 Empty 或 Success 的 props。

四个状态组件:Loading / Empty / Failure / Success

Loading:请求进行中

如果没有任何缓存数据且请求仍在进行中,Cell 渲染 Loading 组件。

本地开发时,如果想捕捉 Cell 等待响应的瞬间,可以把浏览器 Inspector 的 Network 面板里的网络速度调成类似 "Slow 3G"。不过,Redwood 自带的 Storybook 是更好的选择——用它开发 Loading(和 Failure)组件,完全不必忍受 Slow 3G 这种临时方案,也不需要故意把应用弄坏。

Empty:无数据时的兜底

如果没有数据,Cell 渲染 Empty 组件。所谓"没有数据",指响应为 1) null 或 2) 空数组([])。

Failure:出错时的兜底

如果出了任何差错,Cell 渲染 Failure 组件。想快速看到效果,可以在 QUERY 里加一个 SDL 中没有定义的字段:

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

但和 Loading 一样,Storybook 通常是开发这个组件的更佳场所。

Failure 组件独有的 errorCode prop 非常实用,可以据此做条件渲染,甚至作为国际化(i18n)的翻译键:

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 的来源可以在 createCell.tsx 中找到:它优先取 queryResult.errorCode,否则从 error.graphQLErrors<a href="https://link.gitcode.com/i/191a13cc36c1c2a9caf628b4f7c16347" target="_blank">0].extensions['code'] 中提取。类型定义见 [cellTypes.ts 的 CellFailureProps(error 甚至允许直接传入用于测试和 Storybook)。

Success:数据就绪时的渲染

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

如前所述,Success 独享 data。但如果你试图从 props 中解构它,会发现它并不存在——这是 Redwood 特意加的一层便利:Redwood 会把 data 展开(spread)进 Success,让你可以直接解构 QUERY 中预期的字段。

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

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

  // ...
}

Redwood 允许你直接这样写:

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

注意,其他 props 仍然可以照常传给 Success——说到底它只是一个普通的 React 组件。这一展开行为对应 createCell.tsx 中 <Success {...props} {...afterQueryData} updating={loading} queryResult={queryResult} /> 的渲染方式。

关于 TypeScript 与 Cells 的配合,可进一步阅读 Utility Types 文档,其中定义了 CellSuccessData、CellSuccessProps、CellFailureProps 等工具类型的用法。

何时该用 Cell?何时不必?

只要你想获取数据,就可以用 Cell。 让 Redwood 去处理何时显示什么,你只需专注于这些状态应该长什么样。

但用 Cell 并非强制。比如一次性查询,随时可以使用 useApolloClient 拿到客户端直接执行查询:

// 在 React 组件中...

client = useApolloClient()

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

可以在 Cell 里执行 Mutation 吗?

完全可以。仓库中的示例项目 example-todo-main 里,TodoListCell 就是一个在 Cell 中同时进行查询与变更(加待办事项)的典型实现。

Redwood 官方并不认为在 Cell 中做 mutation 是反模式,恰恰相反——你的 Cell 可能会承载大量逻辑,在很多方面真正成为应用的枢纽。同时请记住:除了"导出特定名称的特定常量"之外,Cells 几乎没有其他规则——普通组件里能做的一切,在 Cell 里照样能做。

框架如何识别一个文件是 Cell?Babel 插件剖析

你只需要让文件名以 "Cell" 结尾,对吗?基本正确,但还有一件事需要知道。

Redwood 会查找所有以 "Cell" 结尾的文件(所以如果你想让它成为 Cell,文件名确实必须以 "Cell" 结尾),但满足以下两个条件的文件会被跳过:

  1. 没有导出名为 QUERY 的常量;
  2. 有默认导出(default export)。

什么时候会用到这个规则?比如你只是想有个文件碰巧以 "Cell" 结尾。除此之外,完全不用在意它。

这一逻辑在 babel-plugin-redwood-cell.ts 中有完整实现,插件的工作流程如下:

  1. 收集导出:遍历文件中的 ExportNamedDeclaration,把名称命中的 EXPECTED_EXPORTS_FROM_CELL 列表(beforeQuery、QUERY、data、isEmpty、afterQuery、Loading、Success、Failure、Empty)的导出名收集到 exportNames 数组;
  2. 判定:在 Program.exit 阶段检查——如果文件已有默认导出(说明它可能已是被包装过的 Cell,或根本不是 Cell),或没有 QUERY/data 导出,就直接返回不做处理(对应源码 babel-plugin-redwood-cell.ts#L75-L87);
  3. 注入代码:在文件顶部自动插入 import { createCell } from '@redwoodjs/web'(如果导出的是 data 而非 QUERY,则改为从 @redwoodjs/web/dist/components/cell/createServerCell 导入 createServerCell,这是 RSC 服务端 Cell 的场景);在文件底部自动追加 export default createCell({ ...exportNames, displayName }),其中 displayName 取自文件名。

也就是说,构建期 Babel 插件 + 运行时 createCell 高阶组件共同完成了"把命名导出装配成完整 Cell"这件"魔法"。装配后的渲染决策树就是 createCell.tsx 中的那段逻辑:

  • 有 error 且有 Failure → 渲染 Failure;没有 Failure → 直接抛出错误;
  • 有 data → 先过 afterQuery,再用 isEmpty 判断:为空且有 Empty 就渲染 Empty,否则渲染 Success;
  • 既无 data 也无 error 且 loading → 渲染 Loading;
  • 到达一个"查询成功但 data 为 null"的意外状态 → 抛出带排查建议的错误(提示检查 Storybook 中查询是否缺少字段、是否为 GraphQL 缓存 bug、是否在查询字段上补充 id)。

值得一提的是,createCell.test.tsx 中有 20 余个 createCell 测试用例,覆盖了各状态渲染、props 透传、错误处理等行为,是理解这套决策树行为细节的最佳参考。

进阶示例:如果不用 Babel,手写一个 Cell 是什么样?

假设 Babel 不会来帮你装配导出,你该怎么自己实现一个 Cell?

以上文"获取 posts"的示例为例,你很可能需要写出类似下面的代码——这段代码本质上就是把 createCell.tsx 的内容抄进你自己的文件:

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

这是相当可观的一段代码——而且全是命令式代码。试想一下:每次要获取一份可能延迟响应的数据,都要把这段逻辑重写一遍?想想就头大。

这正是 Cells 的核心价值所在:Redwood 把这段样板逻辑固化在框架里(当前仓库的运行时实现是 createCell.tsx,并且会依据 RWJS_ENV.RWJS_EXP_STREAMING_SSR 环境开关在普通实现与 Suspense 版实现 createSuspendingCell.tsx 之间自动切换),再加上构建期的 Babel 自动装配,让你只需要用七个命名导出描述 UI,剩下的一切交给框架。

登录后查看全文
redwood