Redwood Cells 完全指南:声明式数据获取与查询生命周期管理
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,以及一个updatingprop,用于表示 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 导出,都会被跳过。
通过判定后,插件会做两件事(这就是"构建期装配"的本质):
- 在文件顶部插入导入语句:
import { createCell } from '@redwoodjs/web'; - 在文件底部追加默认导出:
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,其核心流程为:
- 剥离
children(Cells 不渲染 children),把其余 props 当作候选变量; - 调用
beforeQuery(variables)得到 options(默认注入cache-and-networkfetch policy); - 若
QUERY是函数,则QUERY(options)求值得到查询; - 调用
useQuery(query, options)拿到error、loading、data与其余queryResult; - 按优先级分支渲染:
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。