Redwood Cells 深度指南:声明式 GraphQL 数据获取的生命周期管理
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返回的大部分字段(作为queryResultprop 传入);- 在此基础上,
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返回的variablesprop 中解构出原始值;或者干脆给 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(后者是文档未提及但对updatingprop 至关重要的配置,它让组件在轮询/重取数据时收到状态更新)。 - 状态分发:
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 工具类型)。