Relay 实战:使用 `useMutationAction_EXPERIMENTAL` 将 Mutation 接入 React 19 Form Actions

原创2026-09-20 13:14:471,714 阅读
文章标签:前端开发工具

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],
);

从中可以提炼出三个要点:

  1. 环境来源:通过 useRelayEnvironment() 从 RelayEnvironmentProvider 上下文获取当前环境,因此它必须在该 Provider 内部使用;
  2. Promise 化封装:内部调用 relay-runtime 的 commitMutation,把 onCompleted 回调的响应通过 resolve 暴露,把 onError 的错误通过 reject 抛出,因此返回的 action 天然可以被 await,也天然能被 React 的 Form Action 生命周期消化;
  3. 引用稳定:用 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 文件,对每个文件执行以下流程:

  1. parseMarkdown.js 提取带 title="文件名" 的代码块与 steps 块;
  2. setupTempDir.js 在临时目录中重建 template/ 工程:写入代码块内容、拷贝 GratsNetwork.ts、生成指向本仓库 relay-runtime / react-relay 源码类型声明的 tsconfig paths 映射、软链 node_modules;
  3. runFixture.js 依次执行 grats(由 TypeScript 源码生成 schema)、relay-compiler(生成 __generated__ 类型产物,可通过 RELAY_COMPILER_BINARY 环境变量或本地 compiler/target/debug/relay 指定)、tsc(对 fixture 与生成产物做类型检查);
  4. 用 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 提供了全链路一致的开发与测试体验。

登录后查看全文
relay