用途
本技能用于指导在 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 }),
})
常见错误
资料列出三类高频错误,并给出错误与正确写法:
-
mutate 传入多个参数(HIGH)。mutation 变量是单一值,需要多个字段时应传入对象。错误写法为
useUpdateTodo().mutate('1', 'Ship'),正确写法为useUpdateTodo().mutate({ id: '1', title: 'Ship' })。 -
卸载后执行每次调用回调(HIGH)。Hook 级回调与 mutation 生命周期绑定;如果 observer 卸载,每次调用的回调可能不会执行。错误写法是在 mutate 的第二个参数中传 onSuccess,正确写法是把 onSuccess 放在 useMutation 配置中。
-
未等待失效完成(HIGH)。返回失效的 promise 可以让 mutation 保持 pending,直到依赖数据刷新完成。错误写法是
onSuccess: () => queryClient.invalidateQueries(...),正确写法是onSuccess: async () => queryClient.invalidateQueries(...)。
适用场景
适用于使用 TanStack Query 管理服务端状态、需要执行写入操作并同步缓存的 React 应用开发场景,例如新增、保存、更新数据后刷新相关查询。
限制
资料未提供关于平台、收费、价格、效果或性能的说明。另可参见 core/implement-optimistic-updates-and-cache-writes,用于在服务端返回前更新缓存的 mutation 副作用。