SuperAPI AI 工具集

tanstack-query-intent-core-write-mutations-and-invalida-1820d5b8

编程与开发

查看项目

更新于 10-16 10:25

技能介绍

用途

本技能用于指导在 TanStack Query 中编写服务端状态的写入逻辑,即围绕 mutation(变更)相关 API 的使用方式。它覆盖的核心 API 包括 useMutation、mutationFn、mutate、mutateAsync、mutationKey、useMutationState、invalidateQueries、setMutationDefaults。

主要能力

资料给出的能力点包括:

  • 基础设置:通过 useMutation 与 useQueryClient 组合,在 onSuccess 中调用 invalidateQueries 使相关查询失效。
  • 从 mutation 响应更新缓存:在 onSuccess 中接收返回数据,并用 setQueryData 写入对应查询键。
  • 追踪相关 mutation:使用 useMutationState,配合 filters(如 mutationKey、status)与 select 提取所需状态。
  • 按 mutation key 设置默认值:通过 QueryClient 的 setMutationDefaults 为指定 mutationKey 提供默认 mutationFn。

使用方式

资料提供了可直接参考的代码示例。基础用法示例:

import { useMutation, useQueryClient } from '@tanstack/react-query'

export function useAddTodo() {
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: async (title: string) => ({ id: Date.now(), title }),
    onSuccess: async () => {
      await queryClient.invalidateQueries({ queryKey: ['todos'] })
    },
  })
}

从 mutation 响应更新缓存:

import { useMutation, useQueryClient } from '@tanstack/react-query'

export function useSaveTodo() {
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: async (todo: { id: string; title: string }) => todo,
    onSuccess: (todo) => {
      queryClient.setQueryData(['todo', todo.id], todo)
    },
  })
}

追踪相关 mutation:

import { useMutationState } from '@tanstack/react-query'

export function usePendingTodoTitles() {
  return useMutationState<string>({
    filters: { mutationKey: ['addTodo'], status: 'pending' },
    select: (mutation) => mutation.state.variables as string,
  })
}

按 mutation key 设置默认值:

import { QueryClient } from '@tanstack/react-query'

export const queryClient = new QueryClient()

queryClient.setMutationDefaults(['addTodo'], {
  mutationFn: async (title: string) => ({ id: Date.now(), title }),
})

常见错误

资料列出三类高频错误,并给出错误与正确写法:

  1. mutate 传入多个参数(HIGH)。mutation 变量是单一值,需要多个字段时应传入对象。错误写法为 useUpdateTodo().mutate('1', 'Ship'),正确写法为 useUpdateTodo().mutate({ id: '1', title: 'Ship' })。

  2. 卸载后执行每次调用回调(HIGH)。Hook 级回调与 mutation 生命周期绑定;如果 observer 卸载,每次调用的回调可能不会执行。错误写法是在 mutate 的第二个参数中传 onSuccess,正确写法是把 onSuccess 放在 useMutation 配置中。

  3. 未等待失效完成(HIGH)。返回失效的 promise 可以让 mutation 保持 pending,直到依赖数据刷新完成。错误写法是 onSuccess: () => queryClient.invalidateQueries(...),正确写法是 onSuccess: async () => queryClient.invalidateQueries(...)。

适用场景

适用于使用 TanStack Query 管理服务端状态、需要执行写入操作并同步缓存的 React 应用开发场景,例如新增、保存、更新数据后刷新相关查询。

限制

资料未提供关于平台、收费、价格、效果或性能的说明。另可参见 core/implement-optimistic-updates-and-cache-writes,用于在服务端返回前更新缓存的 mutation 副作用。