浏览文档目录
第 06 课 · 写入数据

从 Server Function 写回缓存

验证网络边界上的输入,通过 Mutation 表达写入状态,再用服务端响应不可变地更新 Query 缓存。

TanStack Query实践24 分钟REV 02Markdown .md
完成后你将能够

能实现有 pending、error、success 状态的创建流程。

01

先守住服务端边界

客户端类型不能替代运行时校验。POST Server Function 在 handler 前使用 validator,把 unknown 转换成可信输入;真实应用还应在这里执行认证与授权。

src/features/issues/issues.tsts
export const createIssue = createServerFn({ method: 'POST' })
  .validator((input: { title: string }) => {
    const title = input.title.trim()
    if (title.length < 3) throw new Error('Title is too short')
    return { title }
  })
  .handler(async ({ data }) => saveIssue(data))
02

用响应更新唯一事实来源

useMutation 管理写入生命周期。成功后优先使用服务端返回的完整对象更新缓存;更新函数要返回新数组,不能原地 push 旧缓存。

src/routes/issues/index.tsxtsx
const queryClient = useQueryClient()
const mutation = useMutation({
  mutationFn: (input: CreateIssueInput) =>
    createIssue({ data: input }),
  onSuccess: (issue) => {
    queryClient.setQueryData<Issue[]>(['issues'], (current = []) => [
      issue,
      ...current,
    ])
  },
})
实践

把本课变成可验证的能力

完成检查点

写入成功后列表和详情缓存保持一致,失败时不会展示未确认的数据。

动手练习

创建 Issue 后把响应写入详情缓存,并仅失效受影响的列表前缀。

验证方法

模拟成功和失败两条路径;成功后直接进入详情无需额外空状态,失败后缓存保持原值。

常见错误
  • 无条件失效整个 Query 缓存。
  • 假设服务端响应与提交输入完全相同。
SOURCE REFERENCES · CHECKED 2026-08-03https://tanstack.com/start/latest/docs/framework/react/guide/server-functionshttps://tanstack.com/query/latest/docs/framework/react/guides/mutationshttps://tanstack.com/query/latest/docs/framework/react/guides/updates-from-mutation-responses