202React-Query：useMutation

详情见官方文档api

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

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

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

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

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

jsx 复制代码

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 实现相同的功能：

jsx 复制代码

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` 钩子，方便安全地回滚。

通过使用 useMutation，您可以将精力从繁琐的异步状态管理中解放出来，专注于构建业务逻辑和用户体验。这是现代 React 数据获取库带来的最大价值。