Relay 实战:使用 `useMutationAction_EXPERIMENTAL` 将 Mutation 接入 React 19 Form Actions
Relay 实战:使用 useMutationAction_EXPERIMENTAL 将 Mutation 接入 React 19 Form Actions
本文以 Relay 仓库中的端到端测试 fixture(packages/relay-e2e-test/fixtures/mutations/useMutationAction-form-action.md)为核心,讲解如何在 React 19 的 <form action={...}> 表单处理器中调用 Relay mutation:利用 React 19 对 Form Actions 自动包裹 startTransition 的机制,让 mutation 与表单提交生命周期、useActionState 无缝集成。读完本文,你将掌握 useMutationAction_EXPERIMENTAL 的完整调用模式、它在 react-relay 中的底层实现,以及如何通过 Relay 的 Markdown 驱动 e2e 测试体系验证这一行为。
背景:React 19 Form Actions 为何适合承载 Mutation
React 19 引入了基于 <form> 的 Actions 机制:当你在 <form action={handler}> 中传入一个函数时,该函数会在表单提交时被调用,并自动获得两方面的能力:
- 自动包裹在
startTransition中:提交动作被视为一次过渡更新,React 可以在其执行期间保持界面响应,并跟踪挂起状态(pending state); - 与
useActionState天然协作:useActionState接收一个 action 函数,返回[state, formAction, isPending],其中formAction可以直接传给<form action={...}>,提交期间由isPending反映挂起状态,action 的返回值会被写入state。
这意味着:一个"表单提交 → 调用 GraphQL mutation → 展示结果"的完整链路,可以用 React 原生的表单生命周期承载,而无需手动管理提交中状态与结果回填。Relay 的 useMutationAction_EXPERIMENTAL 正是为这种模式设计的——它返回一个"可直接作为 action 使用的异步提交函数"。
API 形态与底层实现
useMutationAction_EXPERIMENTAL 位于 packages/react-relay/relay-hooks/useMutationAction_EXPERIMENTAL.js,其类型签名在 packages/react-relay/relay-hooks/useMutationAction_EXPERIMENTAL.d.ts 中定义为:
export function useMutationAction_EXPERIMENTAL<TMutation extends OperationType>(
mutation: GraphQLTaggedNode,
): (variables: VariablesOf<TMutation>) => Promise<TMutation['response']>;
即:传入一个 GraphQL mutation 标签,返回一个接收变量、返回 Promise 的异步提交函数。从源码看,它被约束为 OperationType(response: unknown)而非更严格的 MutationParameters——注释说明这是因为 Flow 源码对 response 不做约束,而更严格的容器会拒绝 @catch 这类 response 为 Result<…> 联合类型的 mutation,这与其他现代 hooks 保持一致。
底层实现的核心逻辑非常简洁:
const commitAction = useCallback(
(variables: TVariables): Promise<TData> => {
return new Promise((resolve, reject) => {
commitMutation(environment, {
mutation,
variables,
onCompleted: (response: TData) => {
resolve(response);
},
onError: (error: Error) => {
reject(error);
},
});
});
},
[environment, mutation],
);
从中可以提炼出三个要点:
- 环境来源:通过
useRelayEnvironment()从RelayEnvironmentProvider上下文获取当前环境,因此它必须在该 Provider 内部使用; - Promise 化封装:内部调用
relay-runtime的commitMutation,把onCompleted回调的响应通过resolve暴露,把onError的错误通过reject抛出,因此返回的 action 天然可以被await,也天然能被 React 的 Form Action 生命周期消化; - 引用稳定:用
useCallback且依赖[environment, mutation]缓存,返回的 action 函数引用稳定,适合直接放入<form action={...}>或传给useActionState而不会导致重复渲染。
其使用注释也明确了两类典型场景——放在 startTransition 中(用于乐观 UI),或直接作为 action prop:
// In a startTransition or action prop:
startTransition(async () => {
setOptimisticValue(newValue);
await commitAction({input: newValue});
});
端到端示例:表单 + useActionState + Mutation
fixture useMutationAction-form-action.md 是一个可运行的完整示例,它由四部分组成:Relay 配置、GraphQL 服务端(Grats)、React 应用、交互验证步骤。
1. Relay 配置
{
"src": "./",
"schema": "./schema.graphql",
"language": "typescript"
}
这是 Relay 编译器的基础配置:src 指定源码目录为当前目录,schema 指向 Grats 生成的 GraphQL schema 文件,language 指定生成 TypeScript 产物(生成的类型位于 __generated__/*.graphql.ts)。
2. 服务端:以 Grats 注解定义 Query 与 Mutation
/** @gqlQueryField */
export function greeting(): string {
return "Enter your name";
}
/** @gqlMutationField */
export async function greetUser(args: { name: string }): Promise<string> {
await new Promise((resolve) => setTimeout(resolve, 100));
return `Hello, ${args.name}!`;
}
这里的 @gqlQueryField / @gqlMutationField 是 Grats 的类型安全 schema 定义方式:服务端只写 TypeScript 函数,Grats 从注解推导出 GraphQL schema。greetUser 中的 100ms 延时用于模拟真实网络往返,方便观察表单的"提交中"状态。
3. 应用层:useLazyLoadQuery + useMutationAction + useActionState
import { Suspense, useActionState } from "react";
import {
RelayEnvironmentProvider,
useLazyLoadQuery,
useMutationAction_EXPERIMENTAL,
} from "react-relay";
import { graphql, Environment } from "relay-runtime";
import { gratsNetwork } from "../GratsNetwork";
import { AppTestQuery } from "./__generated__/AppTestQuery.graphql";
import { AppGreetUserMutation } from "./__generated__/AppGreetUserMutation.graphql";
const testEnvironment = new Environment({ network: gratsNetwork });
function GreetingForm() {
const data = useLazyLoadQuery<AppTestQuery>(
graphql`
query AppTestQuery {
greeting
}
`,
{},
);
const commitAction =
useMutationAction_EXPERIMENTAL<AppGreetUserMutation>(
graphql`
mutation AppGreetUserMutation($name: String!) {
greetUser(name: $name)
}
`,
);
const [message, formAction, isPending] = useActionState(
async (_prev: string | null | undefined, formData: FormData) => {
const name = formData.get("name") as string;
const response = await commitAction({ name });
return response.greetUser;
},
data.greeting,
);
return (
<div>
<div>{message}</div>
<form action={formAction}>
<input name="name" defaultValue="Alice" />
<button type="submit" disabled={isPending}>
Greet
</button>
</form>
{isPending && <div>Submitting...</div>}
</div>
);
}
export default function TestApp() {
return (
<RelayEnvironmentProvider environment={testEnvironment}>
<Suspense fallback={<div>Loading...</div>}>
<GreetingForm />
</Suspense>
</RelayEnvironmentProvider>
);
}
这段代码演示了完整的三层协作:
数据读取层:useLazyLoadQuery<AppTestQuery> 先通过 AppTestQuery 查询拿到初始 greeting 字段("Enter your name"),作为 useActionState 的初始 state。
Mutation 提交层:useMutationAction_EXPERIMENTAL<AppGreetUserMutation> 接收 AppGreetUserMutation 标签,返回 commitAction({ name }) 异步函数。
表单状态层:useActionState 接收一个异步 action——它从 FormData 中读取 name 字段,调用 commitAction({ name }) 发起 mutation,并把响应中的 greetUser 字段作为新的 state 返回。useActionState 返回的 [message, formAction, isPending] 三元组中:
message:当前状态,初始为查询返回的data.greeting,提交成功后更新为"Hello, {name}!";formAction:直接绑定到<form action={formAction}>,React 会自动在提交时以startTransition包裹执行;isPending:提交期间的挂起标记,用于禁用提交按钮(disabled={isPending})并渲染"Submitting..."提示。
由于 React 19 的 Form Action 自动包裹 startTransition,commitAction 中的 mutation 请求在过渡中执行,UI 更新(如 isPending 切换与结果回填)具备过渡优先级;异步 action 返回的 Promise resolve 后,useActionState 会把返回值写入 state,完成"输入 → 提交 → 结果展示"的闭环,期间无需任何手动的事件处理和 loading 状态管理。
注意 environment 使用的是测试 fixture 中的 gratsNetwork——这是一个基于 graphql-js 的进程内 Network(见 packages/relay-e2e-test/GratsNetwork.ts),它把 Relay 的请求直接交给内存中的 GraphQL schema 执行,因此 fixture 可以脱离真实服务器运行;在实际业务中,此处替换为真实的 HTTP Network 即可。
4. 交互验证步骤
wait "Enter your name"
click button "Greet"
wait "Submitting..."
wait "Hello, Alice!"
这段 steps 块是 Relay e2e 体系的自定义交互 DSL,由 packages/relay-e2e-test/src/runInteractions.js 解析执行,支持三种动作:click(点击)、type(输入)、wait(等待文本出现),且均可通过 role 定位带可访问名称的元素。其执行逻辑为:
wait:使用screen.findByText/screen.findByRole异步等待目标出现;click/type:通过userEvent(getByText或getByRole)模拟真实用户交互。
对应到本示例:页面先渲染初始问候语"Enter your name",点击"Greet"按钮后触发表单提交,先出现"Submitting..."(验证 isPending 生效),随后 mutation 完成、结果回填,出现"Hello, Alice!"(验证 useActionState 状态更新成功)。
该 fixture 的最终快照 useMutationAction-form-action.snap.md 记录了渲染结果:<div>Hello, Alice!</div> 与绑定 action 的 <form>、值为 Alice 的 <input name="name">、以及 Greet 提交按钮,验证了整条链路端到端正确。
这个 fixture 是如何被自动执行的
上述 Markdown 不只是文档,而是一个可运行的测试。Relay 的 e2e 测试体系由 packages/relay-e2e-test/tests/fixtures-test.js 驱动:它扫描 fixtures/ 下所有 .md 文件,对每个文件执行以下流程:
- parseMarkdown.js 提取带
title="文件名"的代码块与steps块; - setupTempDir.js 在临时目录中重建
template/工程:写入代码块内容、拷贝GratsNetwork.ts、生成指向本仓库relay-runtime/react-relay源码类型声明的 tsconfigpaths映射、软链node_modules; - runFixture.js 依次执行
grats(由 TypeScript 源码生成 schema)、relay-compiler(生成__generated__类型产物,可通过RELAY_COMPILER_BINARY环境变量或本地compiler/target/debug/relay指定)、tsc(对 fixture 与生成产物做类型检查); - 用 React Testing Library 渲染
App.tsx,执行steps交互,最终把 HTML 快照与steps执行结果对比.snap.md文件。
运行时,GratsNetwork.ts 用 Network.create 同时提供 fetch 与 subscribe 实现,将解析后的 GraphQL 文档交给 graphql-js 的 execute / subscribe 在内存中执行。运行方式见 packages/relay-e2e-test/README.md:仓库根目录执行 yarn test:e2e 运行全部 fixture,或通过 yarn test:e2e -- --testNamePattern useMutationAction-form-action 只运行本用例;快照用 yarn test:e2e -u 重写,--ci 模式下只读校验。
同系列场景对比:从按钮到表单
本 fixture 并非孤例——fixtures/mutations/ 目录下还有多个 useMutationAction 系列用例,可以帮你理解该 hook 的完整能力边界(均为 EXPERIMENTAL 状态,API 可能演进):
- useMutationAction.md:最基础的用法——按钮点击后在
startTransition中调用 action,展示响应结果,对应"手动 startTransition"场景; useMutationAction-optimistic.md:结合useOptimistic的乐观 UI 更新(这也是该 hook 注释中明确支持的用法);useMutationAction-form-action.md(本文主题):接入 React 19<form action={...}>,由表单生命周期自动完成 transition 包裹;useMutationAction-sequential.md:多次提交的顺序执行语义;- 系列中的
*-field-error、*-network-error-*用例:覆盖字段级错误与网络错误的处理路径(网络层错误通过 Promise reject 暴露,可被 action 的 async/await 捕获)。
对比 useMutationAction.md 中的手动模式可以发现,Form Action 版本省去了 useState + useTransition + onClick 的手工编排:isPending 与状态回填全部由 useActionState 接管,这正是"mutation 与表单提交生命周期自然集成"的含义。
使用要点与注意事项
结合源码与示例,在使用 useMutationAction_EXPERIMENTAL 接入表单时应注意:
- 必须在
RelayEnvironmentProvider内使用:hook 依赖useRelayEnvironment()获取环境,脱离 Provider 会报错; - mutation 标签必须是编译产物:
graphql\...`标签由 Babel/Relay 编译器处理并生成带类型的GraphQLTaggedNode,配合generated/AppGreetUserMutation.graphql.ts` 中的类型参数获得完整的变量与响应类型推断; - 响应直接来自
onCompleted:action 返回的 Promise 解析值即 mutation 的响应对象(如response.greetUser),可直接作为useActionState的返回值,但要注意字段可空性(如?.兜底); - 错误处理:
commitMutation的onError被转为 Promise reject,因此可以像普通 async 函数一样用 try/catch 处理网络错误,或交由错误边界兜底; EXPERIMENTAL前缀:该 API 与 React 19 的 Action/useActionState机制深度耦合,使用时需确认你的 React 版本与 react-relay 版本支持,并关注其后续 API 演进。
整体来看,useMutationAction_EXPERIMENTAL 把 Relay mutation 的调用收敛为一个可 await 的 action 函数,使其能嵌入 React 19 的表单与过渡更新体系——从本文的 fixture 可以看到,从服务端 Grats 定义、Relay 配置,到 useActionState 驱动的完整表单,再到可自动执行的 e2e 验证,Relay 提供了全链路一致的开发与测试体验。