RedwoodJS Cells 深度指南:用声明式约定驾驭 GraphQL 数据获取生命周期
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!]vsposts: [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" 结尾),但满足以下两个条件的文件会被跳过:
- 没有导出名为
QUERY的常量; - 有默认导出(default export)。
什么时候会用到这个规则?比如你只是想有个文件碰巧以 "Cell" 结尾。除此之外,完全不用在意它。
这一逻辑在 babel-plugin-redwood-cell.ts 中有完整实现,插件的工作流程如下:
- 收集导出:遍历文件中的
ExportNamedDeclaration,把名称命中的EXPECTED_EXPORTS_FROM_CELL列表(beforeQuery、QUERY、data、isEmpty、afterQuery、Loading、Success、Failure、Empty)的导出名收集到exportNames数组; - 判定:在
Program.exit阶段检查——如果文件已有默认导出(说明它可能已是被包装过的 Cell,或根本不是 Cell),或没有QUERY/data导出,就直接返回不做处理(对应源码 babel-plugin-redwood-cell.ts#L75-L87); - 注入代码:在文件顶部自动插入
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,剩下的一切交给框架。