202React-Query：useMutation-程序员充电站

详情见官方文档api

📝 告别繁琐的状态管理：拥抱 TanStack Query 的`useMutation`

在 React 应用中处理数据的创建、更新和删除（即 Mutation 操作）是日常开发的核心。然而，手动管理这些操作的加载（Loading）、错误（Error）和成功（Success）状态，并确保缓存数据同步，往往是费时费力的重复工作。

本文将对比传统的状态管理方式与 TanStack Query (React Query) 的useMutationHook，展示后者如何让您的代码更清晰、更健壮。

🚀 一、传统的数据修改模式：样板代码的噩梦

假设我们需要实现一个“添加评论”的功能。在没有使用 TanStack Query 之前，我们通常需要在组件中手动管理所有的异步状态：

import React, { useState } from 'react'; import { submitComment } from '../api'; // 假设的API函数 function TraditionalCommentForm({ postId }) { // 手动管理三个核心状态 const [isSubmitting, setIsSubmitting] = useState(false); const [error, setError] = useState(null); const [commentText, setCommentText] = useState(''); const handleSubmit = async (e) => { e.preventDefault(); setIsSubmitting(true); // 1. 开始提交 try { await submitComment(postId, commentText); // 2. 提交成功：清空表单，并可能需要手动通知其他组件刷新 setCommentText(''); setError(null); } catch (err) { // 3. 提交失败：设置错误信息 setError(err.message); } finally { // 4. 无论成功或失败，结束加载状态 setIsSubmitting(false); } }; return ( <form onSubmit={handleSubmit}> {/* ... 表单输入略 ... */} <button type="submit" disabled={isSubmitting}> {isSubmitting ? '提交中...' : '提交'} </button> {error && <p style={{ color: 'red' }}>错误: {error}</p>} {/* 如何刷新评论列表？这是一个待解决的问题！ */} </form> ); }

传统模式的痛点：

状态冗余：每次涉及数据修改的组件都要重复编写isSubmitting、error、isSuccess这些状态。
逻辑复杂：必须在try/catch/finally块中精确管理状态的切换，一旦遗漏或出错（例如没有在finally中关闭isSubmitting），就会导致 UI 错误。
缓存脱节：提交成功后，您需要找到一种手动的方式（例如全局状态管理或回调函数）来通知展示评论列表的组件重新获取数据，以保证数据同步。

🔥 二、拥抱`useMutation`：声明式的数据修改

useMutation将所有这些繁琐的异步状态管理和缓存同步逻辑抽象到 Hook 内部。我们只需要声明**“做什么”，而无需关心“如何管理状态”**。

1. 自动化的状态管理

使用useMutation实现相同的功能：

import { useMutation, useQueryClient } from '@tanstack/react-query'; import { submitComment } from '../api'; function CommentFormWithMutation({ postId }) { const queryClient = useQueryClient(); const [commentText, setCommentText] = useState(''); // 1. 声明 mutation const { mutate, // 触发 mutation 的函数 isPending, // 替代 isSubmitting isError, // 替代 error != null isSuccess, // 提交成功状态 error, } = useMutation({ mutationFn: (newComment) => submitComment(postId, newComment), // 实际的 API 调用 // 2. 成功后的回调：缓存同步的核心！ onSuccess: () => { // 提交成功后，使“评论列表”查询失效 // 这将导致展示评论列表的 useQuery 自动在后台重新拉取最新数据 queryClient.invalidateQueries({ queryKey: ['postComments', postId] }); setCommentText(''); // 清空表单 }, // 3. 失败后的回调： onError: (err) => { console.error("提交失败:", err.message); } }); const handleSubmit = (e) => { e.preventDefault(); mutate(commentText); // 一行代码触发提交 }; // 4. 使用内置状态进行条件渲染 return ( <form onSubmit={handleSubmit}> {/* ... 表单输入略 ... */} <button type="submit" disabled={isPending}> {isPending ? '提交中...' : '提交'} </button> {isError && <p style={{ color: 'red' }}>错误: {error.message}</p>} {isSuccess && <p style={{ color: 'green' }}>评论提交成功！</p>} </form> ); }

2. 缓存同步：`invalidateQueries`的魔力

这是useMutation与传统方法最大的区别。传统方法需要您自己想办法通知数据列表刷新。

而使用useMutation，通过在onSuccess中调用queryClient.invalidateQueries，您可以声明式地告诉 TanStack Query：

“我刚刚修改了 ID 为postId的帖子下的评论，请你将所有查询键为['postComments', postId]的数据标记为过期，并自动在后台重新拉取。”

这完全解耦了数据修改组件和数据展示组件，确保了应用数据的强一致性。

🌟 总结核心区别

特性	传统方法 (`useState`)	`useMutation`(TanStack Query)
状态管理	手动定义`isLoading`,`error`,`isSuccess`等状态。	自动提供互斥的、可靠的状态。
错误处理	需要在`try/catch`中手动设置`error`状态。	自动捕获并提供`isError`和`error`对象。
缓存同步	需要手动触发回调或使用全局状态管理来强制刷新。	通过`onSuccess`中的`invalidateQueries`自动在后台刷新相关数据。
乐观更新	实现逻辑复杂，容易引入 Bug。	提供结构化的`onMutate`和`onError`钩子，方便安全地回滚。