TanStack Query基础:查询、缓存、变更与失效处理
了解 howUseQuery、queryKey、staleTime、gcTime、useMutation 以及 invalidation 如何协同工作,从而在 React 中无需手动编写 fetch effects 即可管理服务器状态。
TanStack Query,前身为React Query,用于管理来自服务器的数据。之所以更名,是因为该库现在不仅能在React环境中使用,还能在Svelte、Vue和Solid等框架中运行。简而言之,它就是一种用于管理服务器状态的状态管理器。
服务器状态与客户端状态
服务器状态指的是源自后端或外部API的数据,如用户信息、产品数据、帖子内容、评论等。这类数据存在于应用程序之外,因此应用程序无法完全控制它。它可能会在应用程序不知情的情况下发生变化,也可能过时,且只能通过异步请求来获取。
客户端状态则属于应用程序本身。例如,模态框是否打开这样的状态仅存在于浏览器中,可通过const [isModalOpen, setIsModalOpen] = useState(false)来表示。Zustand、Redux和Jotai都是处理这类状态的常用工具。
手动方法及其成本
在没有库的情况下,获取用户信息通常需要依赖三个状态变量。
const [users, setUsers] = useState([])
const [loading, setLoading] = useState(false)
const [error, setError] = useState(null)
然后通过特效来显示加载状态。
useEffect(() => {
async function fetchUsers() {
try {
setLoading(true) const res = await fetch(
"https://jsonplaceholder.typicode.com/users"
) const data = await res.json() setUsers(data)
} catch (err) {
setError(err)
} finally {
setLoading(false)
}
} fetchUsers()
用户数据被获取并存储在状态中,同时会设置加载标志并捕获错误。随着应用程序的扩展,这种模式会在各个地方重复出现,每个部分都需要处理加载状态、错误状态、缓存、重新获取数据、后台重新获取数据、同步以及重试等功能。当这样的需求遍布整个大型代码库时,就会产生混乱不堪的代码。
查询时也是如此
一个简单的钩子就能替代那些冗余的代码。
function Users() {
const {
data,
isLoading,
error
} = useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
随后,该组件会根据状态进行分支处理。
if (isLoading) {
return <p>Loading...</p>
} if (error) {
return <p>Something went wrong</p>
} return (
<ul>
{data.map(user => (
<li key={user.id}>
{user.name}
</li>
))}
</ul>
)
}
TanStack Query 负责处理与服务器数据相关的基础设施。相比 useEffect 结合 useState 的方式,它的优势在于内置了缓存功能。数据一旦获取就会存入缓存,之后可再次使用,从而减少不必要的 API 请求。加载、成功和错误状态会自动被记录,因此无需手动编写和维护相关逻辑。
设置
安装该包即可。
npm install @tanstack/react-query
然后创建一个 QueryClient 并将其提供给应用程序。
const queryClient = new QueryClient();
root.render(
<QueryClientProvider client={queryClient}>
<App />
</QueryClientProvider>
);
使用 useQuery 读取数据
useQuery 钩子用于处理数据读取操作,即获取服务器数据的任何操作。其基本调用方式如下:
const { data,
isPending,
error } = useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
它需要一个选项对象,其中有两个属性最为重要:queryFn和queryKey。
queryFn是TanStack Query用来获取数据的函数。它可以直接返回数据,或者以Promise的形式返回;在出错时,应抛出异常或返回一个被拒绝的Promise。
async function fetchUsers() {
const res = await fetch("/api/users")
if (!res.ok) {
throw new Error("Failed to fetch users")
}
return res.json()
}
然后它插入钩子中:
useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
queryKey用于唯一标识一个查询及其缓存数据。queryFn所使用的变量通常应包含在键中。例如,["users"]可表示所有用户,["todo", 1]表示ID为1的待办事项,而["products", "laptops"]则表示笔记本电脑。
该钩子函数会返回一个对象,其中包含查询的状态(加载中、出错或成功)、数据以及用于重新获取数据的函数。
缓存的作用
这正是该库发挥作用的地方。获取到的数据会被自动存储并重复使用,从而避免重复调用,进而提升性能并缩短结果显示的时间。
假设组件 A 请求 ["users"]。TanStack Query 会获取该数据并将其缓存。之后,组件 B 也请求相同的键值,此时库会检测到数据已存在缓存。无需每个组件都自行保存副本,TanStack Query 会统一管理服务器状态的缓存版本。这正是普通 fetch() 方法与该库之间最大的区别之一。
staleTime 和 gcTime
staleTime 解决的是这样一个问题:这些数据应被视为有效多久?
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60,000 // 60 seconds
})
在如此设置下,数据在最初的60秒内是最新的。一分钟后数据就会变旧,从而触发重新获取操作并进行后台刷新。虽然数据可能已经过时,但“变旧”并不意味着已被删除。一旦数据变旧,当有相应触发条件出现时,比如窗口重新获得焦点或某个组件加载完成,就可以重新获取数据。
忽略数据变旧的问题会导致用户在再次访问页面时产生不必要的请求。
User visits page
↓
Fetch users
↓
User navigates away
↓
User comes back
↓
Fetch users again
如果没有任何变化,第二次请求就会白费。更长的有效期限可以避免这种情况:
staleTime: 5 * 60 * 1000
这样会将数据标记为新鲜状态,有效期为五分钟。请记住,staleTime用于控制数据的新鲜度,而非重新获取数据的间隔时间。
还有gcTime,即垃圾回收时间。它决定了未被使用、未被监控的缓存数据在内存中保留多久后会被回收。
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
gcTime: 60000
})
总而言之,staleTime表示数据保持有效的时间长度,而gcTime则表示未被使用的缓存条目会保留的时间。它们解决的是不同的问题。
重新获取数据
过期的查询可以在组件加载、窗口重新获得焦点或网络重新连接时重新获取数据,而且这些行为都是可配置的。同时也支持手动重新获取数据。
const { refetch } = useQuery(...)
refetch()
也可以进行投票调查。
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
refetchInterval: 30,000
})
在查询处于活跃状态时,它会大约每30秒重新获取数据一次。重新获取数据会将过时的数据替换为来自后端的最新数据。
使用 useMutation 更改数据
到目前为止所有操作都是用于读取数据。而创建、更新或删除数据(POST、PUT、PATCH、DELETE)则通过 useMutation 钩子来实现。例如,以下是创建用户的操作,首先需要定义突变函数。
async function createUser(user) {
const response = await fetch(
"https://jsonplaceholder.typicode.com/users",
{
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(user),
}
);
if (!response.ok) {
throw new Error("Failed to create user");
}
return response.json();
}
接下来它会被传递给 useMutation。
import { useMutation } from "@tanstack/react-query";
function CreateUser() {
const mutation = useMutation({
mutationFn: createUser,
});
return (
<button
onClick={() =>
mutation.mutate({
name: "John Doe",
email: "john@example.com",
})
}
disabled={mutation.isPending}
>
{mutation.isPending ? "Creating..." : "Create User"}
</button>
);
}
export default CreateUser;
点击按钮会通过 mutation.mutate() 触发变异。
Button click
↓
mutation.mutate(user)
↓
createUser(user)
↓
POST request
↓
Server
请注意,createUser()从未被直接调用。组件会调用mutation.mutate(),而TanStack Query则会执行该函数。
与查询类似,变异操作也带有状态标志。
const {
mutate,
isPending,
isSuccess,
isError,
error,
data,
} = useMutation({
mutationFn: createUser,
});
他们负责驱动用户界面。
<button
onClick={() => mutate({ userName: "delfina ghimire" })}
disabled={isPending}
>
{isPending ? "Creating..." : "Create user"}
</button>
一旦调用 mutate(),该操作会经历多个状态:
isPending:操作正在执行中。isSuccess:操作已成功完成。isError:操作失败。data:操作成功时的结果。error:操作失败时的详细信息。mutate:触发函数,用于接收操作函数所需的参数。
这样一来,在执行创建、更新或删除操作时提供反馈就变得十分简单。
QueryClient与数据失效处理
QueryClient 是一个核心对象,负责管理缓存并协调查询与变更的操作方式。它最初是通过 new QueryClient() 创建的,在组件中则通过 useQueryClient() 来访问。该对象支持使查询失效、更新缓存数据、删除缓存数据、重置查询以及预加载数据。常见的调用方式是 queryClient.invalidateQueries({ queryKey: ["users"] })。
在执行变更操作后,使查询失效尤为重要。当变更操作修改了服务器端的数据时,相关的查询可能会持有过时的结果,通过使这些查询失效可以将其标记为过期,从而需要重新获取数据。假设缓存中存储了两个用户信息:
[
{ id: 1, userName: "delfina ghimire" },
{ id: 2, userName: "spiderman ghimire" },
]
随后会创建一个新用户。
mutation.mutate({
userName: "ironman ghimire",
});
服务器现在有三个用户,但缓存中仍显示为两个。["users"]查询可被标记为过期。首先获取客户端信息:
const queryClient = useQueryClient();
然后,该变异在成功时会失效。
const mutation = useMutation({
mutationFn: createUser,
onSuccess: () => {
queryClient.invalidateQueries({
queryKey: ["users"],
});
},
});
流程如下:
Create Users (Mutation)
↓
Server data changes
↓
Invalidate ["users"]
↓
Query becomes stale
↓
Refetch
↓
UI gets fresh data
为明确区分这两个概念:invalidate会将缓存数据标记为过期,而refetch则会立即重新加载该数据。取消有效查询通常会触发自动重新加载。
整体架构
这些组件共同构成了一个完整的流程:
- TanStack Query负责管理服务器数据。
- 读取操作通过
useQuery实现。 - 获取到的数据会被存入查询缓存。
staleTime决定缓存数据在何时仍被视为有效。gcTime决定未使用的缓存条目可保留的时间长度。- 重新加载功能则决定何时再次获取数据。
- 数据的创建、更新和删除操作通过
useMutation完成。 - QueryClient负责协调查询、变更操作以及缓存管理。
- 查询失效机制用于指示缓存数据已过时。
明确了这些关系之后,理解这个库就容易多了。