使用 useMutation 执行变更与使缓存失效
使用 useMutation 发送 POST 请求，成功后使相关查询失效，让列表自动刷新，并在请求进行期间显示乐观界面反馈。
使用 useMutation 执行变更与使缓存失效 是 CoddyKit 上的免费 React Native Academy 课时。 这是第 2 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 React Native Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 React Native Academy 课程共包含 4 节课。
本课时的部分内容尚未翻译，以英文显示。
What Is a Mutation?
In React Query terminology, a mutation is any operation that changes server data — POST, PUT, PATCH, or DELETE requests. While useQuery fetches and caches data, useMutation handles data modification with loading, error, and success states, plus powerful side-effect callbacks.
Separating queries (reads) from mutations (writes) is a key conceptual pattern. Mutations don't cache their results — they trigger side effects and then cause related queries to refetch fresh data.
useMutation Basics
useMutation takes a mutationFn — an async function that performs the write operation. It returns a mutate function (or mutateAsync for Promise-based usage) that you call when the user triggers the action.
Unlike useQuery, mutations don't run automatically. They wait for you to call mutate(variables). The hook provides isPending, isError, isSuccess, error, and data state from the mutation's response.
import { useMutation } from '@tanstack/react-query';
async function createPost(newPost) {
const response = await fetch('https://api.example.com/posts', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(newPost),
});
if (!response.ok) throw new Error('Failed to create post');
return response.json();
}
const { mutate, isPending, isError } = useMutation({
mutationFn: createPost,
});Calling mutate and mutateAsync
Call mutate(variables) to trigger the mutation. The variables argument is passed directly to your mutationFn. mutate is fire-and-forget — it doesn't return a Promise. Use the hook's onSuccess and onError callbacks to respond to the result.
Use mutateAsync(variables) instead when you need to await the result in an async function (e.g., to navigate after a successful post). Always wrap mutateAsync in try/catch — unhandled rejections will cause errors.
const { mutate, mutateAsync, isPending } = useMutation({
mutationFn: createPost,
});
// Using mutate (fire-and-forget):
function handleSubmit() {
mutate({ title: 'My Post', body: postContent });
}
// Using mutateAsync (awaitable):
async function handleSubmitAndNavigate() {
try {
const newPost = await mutateAsync({ title: 'My Post', body: postContent });
navigation.navigate('PostDetail', { id: newPost.id });
} catch (err) {
Alert.alert('Error', err.message);
}
}onSuccess: Callback After Mutation
The onSuccess callback fires when the mutation completes successfully. It receives the mutation result data and the variables that were passed to mutate. Use onSuccess to invalidate related queries, show success feedback, reset forms, or navigate away.
You can define onSuccess at the hook level (for logic that always applies) and also pass it as a second argument to mutate(variables, { onSuccess }) for per-call customization.
import { useMutation, useQueryClient } from '@tanstack/react-query';
const queryClient = useQueryClient();
const { mutate } = useMutation({
mutationFn: createPost,
onSuccess: (newPost, variables) => {
// Refresh the posts list:
queryClient.invalidateQueries({ queryKey: ['posts'] });
// Show success:
Alert.alert('Post created!', newPost.title);
// Reset form:
resetForm();
},
onError: (error) => {
Alert.alert('Error', error.message);
},
});Cache Invalidation After Mutation
Cache invalidation is the process of marking cached queries as stale after a mutation so they refetch fresh data. Use queryClient.invalidateQueries with a query key. Partial key matching is supported — invalidating ['posts'] invalidates all queries whose key starts with ['posts'], including ['posts', userId].
Invalidation triggers background refetches for all active (mounted) queries with matching keys. Components using those queries will show fresh data within one network round-trip.
const { mutate: deletePost } = useMutation({
mutationFn: (postId) =>
fetch('/api/posts/' + postId, { method: 'DELETE' }),
onSuccess: (data, postId) => {
// Invalidate the posts list:
queryClient.invalidateQueries({ queryKey: ['posts'] });
// Also invalidate the specific post's cache:
queryClient.invalidateQueries({ queryKey: ['post', postId] });
},
});Optimistic Updates
Optimistic updates immediately update the UI before the server confirms the mutation. If the mutation succeeds, the speculative change is confirmed. If it fails, the UI rolls back to the previous state. This makes interactions feel instantaneous — no waiting for the server.
Implement optimistic updates in onMutate: save the current cache snapshot, update the cache immediately, then roll back in onError if needed. React Query provides queryClient.setQueryData to manually update the cache.
const { mutate: likePost } = useMutation({
mutationFn: (postId) => fetch('/api/posts/' + postId + '/like', { method: 'POST' }),
onMutate: async (postId) => {
await queryClient.cancelQueries({ queryKey: ['posts'] });
const snapshot = queryClient.getQueryData(['posts']);
// Optimistically add like:
queryClient.setQueryData(['posts'], (old) =>
old.map(p => p.id === postId ? { ...p, likes: p.likes + 1 } : p)
);
return { snapshot }; // return for rollback
},
onError: (err, postId, context) => {
queryClient.setQueryData(['posts'], context.snapshot); // rollback
},
});Mutation Status and UI Feedback
Use mutation status fields to provide appropriate UI feedback. isPending is true while the mutation is in flight — disable the submit button and show a spinner. isSuccess is true after completion — show a success message. isError is true if it failed — show the error message.
React Query resets mutation status automatically after a configurable gcTime period. To reset it manually (e.g., to allow the user to retry), call the reset() function returned by the hook.
const { mutate, isPending, isError, isSuccess, error, reset } = useMutation({
mutationFn: submitForm,
});
return (
<View>
<TextInput value={text} onChangeText={setText} editable={!isPending} />
<Button
title={isPending ? 'Submitting...' : 'Submit'}
onPress={() => mutate({ text })}
disabled={isPending}
/>
{isError && <Text style={{ color: 'red' }}>{error.message}</Text>}
{isSuccess && <Text style={{ color: 'green' }}>Saved!</Text>}
</View>
);Updating Cache Directly After Mutation
Instead of invalidating and refetching, you can directly update the cache with the mutation response using queryClient.setQueryData. This is more efficient when the server returns the updated data in the mutation response — you can add it to the list without an extra network request.
This pattern — set cache from server response rather than invalidate — saves a network round-trip and is useful for lists where you want to append the new item immediately.
const { mutate } = useMutation({
mutationFn: createPost,
onSuccess: (newPost) => {
// Append new post to cached list directly:
queryClient.setQueryData(['posts'], (oldPosts) => {
if (!oldPosts) return [newPost];
return [newPost, ...oldPosts]; // prepend new post
});
// No invalidation needed — cache is already up to date!
},
});Global Mutation Callbacks via QueryClient
You can define global mutation callbacks in the QueryClient's defaultOptions.mutations for logging, error reporting, or token refresh that should apply to every mutation in the app. Local mutation options override global ones — both can coexist.
A common use case is a global onError callback that checks for 401 Unauthorized responses and triggers a logout or token refresh flow for every mutation, without repeating this logic in each individual useMutation call.
const queryClient = new QueryClient({
defaultOptions: {
mutations: {
onError: (error) => {
// Global error handling for all mutations:
if (error.status === 401) {
handleUnauthorized();
} else {
console.error('Mutation error:', error.message);
}
},
},
},
});Mutations with File Uploads
Mutations handle file uploads by accepting FormData as the variables. The mutationFn creates a FormData object and sends it with fetch using the multipart/form-data content type. React Query manages the loading and error state the same way as any other mutation.
For large file uploads, track progress using a custom fetch wrapper with XHR, storing progress in a separate state variable updated via the onUploadProgress pattern.
const { mutate: uploadPhoto, isPending } = useMutation({
mutationFn: async ({ uri, userId }) => {
const formData = new FormData();
formData.append('photo', {
uri,
type: 'image/jpeg',
name: 'photo.jpg',
});
formData.append('userId', userId);
const response = await fetch('/api/photos', {
method: 'POST',
body: formData,
// Do NOT set Content-Type — let fetch set multipart boundary
});
return response.json();
},
onSuccess: () => queryClient.invalidateQueries({ queryKey: ['photos'] }),
});Chaining Mutations
For workflows that require multiple sequential server operations (e.g., create order then process payment), chain mutations using mutateAsync in sequence. Each mutation can use the result of the previous one as its input. Wrap the chain in try/catch for error handling.
If intermediate steps fail, you may need to roll back earlier steps manually or trigger compensating transactions. Design your API for atomicity where possible to simplify client-side error recovery.
const { mutateAsync: createOrder } = useMutation({ mutationFn: apiCreateOrder });
const { mutateAsync: processPayment } = useMutation({ mutationFn: apiProcessPayment });
async function handleCheckout(cartData, paymentInfo) {
try {
const order = await createOrder(cartData);
const payment = await processPayment({ orderId: order.id, ...paymentInfo });
queryClient.invalidateQueries({ queryKey: ['orders'] });
navigation.navigate('OrderConfirmation', { orderId: order.id });
} catch (error) {
Alert.alert('Checkout failed', error.message);
}
}Quick Check
Test your understanding of React Native Mobile Development concepts from this lesson.
Lesson Recap
In this lesson you learned: useMutation handles write operations (POST/PUT/DELETE) with isPending, isError, and isSuccess state, onSuccess is the primary place to call queryClient.invalidateQueries to refresh related cached data, and optimistic updates via onMutate immediately update the cache with a rollback snapshot for if the server request fails. Next up we persist the React Query cache to AsyncStorage for offline-first behavior.
常见问题解答
「使用 useMutation 执行变更与使缓存失效」课时是免费的吗？
是的 — 「使用 useMutation 执行变更与使缓存失效」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 React Native Academy 课程的其余内容，请升级到 CoddyKit PRO。 React Native Academy 课程共包含 4 节课。
「使用 useMutation 执行变更与使缓存失效」这节课中我会学到什么？
使用 useMutation 发送 POST 请求，成功后使相关查询失效，让列表自动刷新，并在请求进行期间显示乐观界面反馈。 你通过在浏览器中直接运行的动手代码来练习 React Native Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 React Native Academy 需要有经验吗？
无需任何先前经验。CoddyKit 上的 React Native Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 2 节课，共 4 节。
「使用 useMutation 执行变更与使缓存失效」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 React Native Academy 课中编写并运行代码吗？
能。每节 React Native Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。
此课程中的所有课时
- QueryClient、QueryClientProvider 与 useQuery
- 使用 useMutation 执行变更与使缓存失效
- 使用 AsyncStorage 持久化查询缓存
- 后台重新获取与过期时间配置