修改 Mutations

与Queries不同，Mutations 主要用于创建、更新或删除数据，或者执行服务器端的副作用操作。为了支持这一点，TanStack Query 提供了 useMutation 钩子。

🌰 示例：添加一个 Todo:

function App() {
  const mutation = useMutation({
    mutationFn: (newTodo) => axios.post("/todos", newTodo),
  });

  return (
    <div>
      {mutation.isPending ? (
        "正在添加 Todo..."
      ) : (
        <>
          {mutation.isError ? <div>发生错误: {mutation.error.message}</div> : null}

          {mutation.isSuccess ? <div>Todo 添加成功！</div> : null}

          <button
            onClick={() => {
              mutation.mutate({ id: new Date(), title: "洗衣服" });
            }}
          >
            创建 Todo
          </button>
        </>
      )}
    </div>
  );
}

mutation 在任何时候都只会处于以下状态之一：

• isIdle 或 status === 'idle'：Mutation 处于空闲状态，或者已重置。

• isPending 或 status === 'pending'：Mutation 正在执行中。

• isError 或 status === 'error'：Mutation 发生了错误。

• isSuccess 或 status === 'success': Mutation 成功完成，数据已可用。

除此之外，还有一些额外信息可用：

• error：当Mutation失败时，可以通过error获取错误信息。

• data：当Mutation成功时，可以通过data获取返回的数据。

在上面的示例中，你可以看到mutate方法接受参数，并将其传递给mutationFn进行处理。

Mutation 的增强功能

在事件处理函数中调用 mutate

在 React 16 及更早版本中，mutate不能直接在事件回调函数中使用，因为 React 事件会被回收。可以通过额外包装一层来解决：

// ❌ 这样在 React 16 及更早版本会报错
const CreateTodo = () => {
  const mutation = useMutation({
    mutationFn: (event) => {
      event.preventDefault();
      return fetch("/api", new FormData(event.target));
    },
  });

  return <form onSubmit={mutation.mutate}>...</form>;
};

// ✅ 正确的写法
const CreateTodo = () => {
  const mutation = useMutation({
    mutationFn: (formData) => fetch("/api", formData);
  });

  const onSubmit = (event) => {
    event.preventDefault();
    mutation.mutate(new FormData(event.target));
  };

  return <form onSubmit={onSubmit}>...</form>;
};

重置 Mutation 状态

如果需要清除 Mutation 产生的 error 或 data，可以使用 reset 方法：

const CreateTodo = () => {
  const [title, setTitle] = useState("");
  const mutation = useMutation({ mutationFn: createTodo });

  const onCreateTodo = (e) => {
    e.preventDefault();
    mutation.mutate({ title });
  };

  return (
    <form onSubmit={onCreateTodo}>
      {mutation.error && <h5 onClick={() => mutation.reset()}>{mutation.error}</h5>}
      <input type="text" value={title} onChange={(e) => setTitle(e.target.value)} />
      <br />
      <button type="submit">创建 Todo</button>
    </form>
  );
};

Mutation 的生命周期回调

useMutation 提供了多个回调，可以在 Mutation 的不同阶段执行副作用（如更新 UI、日志记录等）：

useMutation({
  mutationFn: addTodo,
  onMutate: (variables) => {
    // Mutation 即将开始！
    // 可以返回一个上下文（context），用于回滚
    return { id: 1 };
  },
  onError: (error, variables, context) => {
    console.log(`回滚操作，撤销 ID 为 ${context.id} 的更新`);
  },
  onSuccess: (data, variables, context) => {
    console.log("Mutation 成功！");
  },
  onSettled: (data, error, variables, context) => {
    console.log("无论成功还是失败，都会执行");
  },
});

这些回调可以返回 Promise，下一个回调会等待前一个回调完成后执行：

useMutation({
  mutationFn: addTodo,
  onSuccess: async () => {
    console.log("我是第一个执行的");
  },
  onSettled: async () => {
    console.log("我是第二个执行的");
  },
});

传递额外的回调

在调用 mutate 时，可以额外指定 onSuccess、onError、onSettled，这些回调会在 Mutation 完成后执行：

mutate(todo, {
  onSuccess: (data, variables, context) => {
    console.log("这是额外的 onSuccess 处理");
  },
  onError: (error, variables, context) => {
    console.log("这是额外的 onError 处理");
  },
  onSettled: (data, error, variables, context) => {
    console.log("这是额外的 onSettled 处理");
  },
});

Mutation 并发与顺序执行

默认情况下，所有 Mutation 是并行执行的。如果希望某些 Mutation 按顺序执行，可以使用 scope，拥有相同 scope.id 的 Mutation 将按照顺序执行。

const mutation = useMutation({
  mutationFn: addTodo,
  scope: {
    id: "todo",
  },
});

使用 mutateAsync 获取 Promise

如果需要在代码中以 await 方式使用 Mutation，可以使用 mutateAsync：

const mutation = useMutation({ mutationFn: addTodo });

try {
  const todo = await mutation.mutateAsync(todo);
  console.log(todo);
} catch (error) {
  console.error(error);
} finally {
  console.log("操作完成");
}

失败时自动重试

默认情况下，Mutation 失败后不会重试。但可以通过 retry 选项开启重试机制：

useMutation({
  mutationFn: addTodo,
  retry: 3, // 失败后最多重试 3 次
});

当设备离线导致 Mutation 失败时，会在设备恢复在线时自动重试。

Mutation 状态的持久化

Mutation 可以持久化存储，以便在应用重启后恢复未完成的 Mutation：

const queryClient = new QueryClient();

queryClient.setMutationDefaults(["addTodo"], {
  mutationFn: addTodo,
  retry: 3,
});

// 持久化 Mutation 状态
const state = dehydrate(queryClient);
hydrate(queryClient, state);

// 重新恢复暂停的 Mutations
queryClient.resumePausedMutations();