-
在模板中使用分组的 state 对象进行类型安全的收窄 — 由于 Vue 的 Ref 包装器限制，TypeScript 无法基于 status ref 对解构的 data 或 error refs 进行类型收窄 来源
<script setup lang="ts">
const { state } = useQuery({ key: ['user'], query: fetchUser })
</script>
<template>
<div v-if="state.status === 'success'">{{ state.data.name }}</div>
<div v-else-if="state.status === 'error'">{{ state.error.message }}</div>
</template>
-
将共享的响应式状态包装在 defineQuery() 中以防止不同步 — 常规组合式函数会为每个组件实例重新创建 refs，导致只有第一个组件能成功触发基于键的响应性 来源
export const useFilteredTodos = defineQuery(() => {
const search = ref('')
const query = useQuery({
key: () => ['todos', { search: search.value }],
query: () => fetchTodos(search.value),
})
return { ...query, search }
})
-
将分层键工厂与 defineQueryOptions() 结合使用以实现严格的类型安全 — 这可以在 queryCache 方法中实现自动类型推断，无需手动类型转换或基于字符串的键拼写错误 来源
export const todoOptions = defineQueryOptions((id: string) => ({
key: ['todos', id],
query: () => fetchTodo(id),
}))
// 推断出的 TData: queryCache.getQueryData(todoOptions('1').key)
-
通过 watch 或全局插件处理副作用，而不是查询选项 — useQuery 有意不包含 onSuccess/onError，以防止在多个组件实例之间重复副作用 来源
-
对于标准的 UI 更新，优先使用 refresh() 而不是 refetch() — refresh() 尊重 staleTime 并会去重进行中的请求，而 refetch() 无论缓存状态如何都会强制进行网络调用 来源
-
使用 meta 属性处理声明式的横切关注点 — 将元数据附加到查询上，以在 PiniaColadaQueryHooksPlugin 内驱动全局 UI 行为（如 toast 消息）来源
-
在执行乐观回滚之前验证缓存状态 — 在 onError 中始终检查当前缓存值是否与乐观值匹配，以避免覆盖来自其他变更的并发成功更新 来源
onError(err, vars, { newTodo, oldTodo }) {
if (newTodo === queryCache.getQueryData(['todos'])) {
queryCache.setQueryData(['todos'], oldTodo)
}
}
-
使用 queryCache.setEntryState() 进行手动状态同步 — 这是手动更新条目的首选方式，因为通过 setQueryData() 将数据设置为 undefined 以重置状态的方式不再受支持 来源
-
在 Nuxt 的 defineQuery 定义中，显式地从 vue-router 导入 useRoute — Nuxt 自动导入的版本可能由于 Suspense 集成而导致不必要的查询触发或 undefined 值 来源
-
在全局存储中使用 enabled getter 来保护“永存”查询 — 防止 Pinia 存储中的查询在必需的响应式参数（如路由参数）缺失时发出无效的网络请求 来源
const result = useQuery({
key: () => ['deck', route.params.id],
query: () => fetchDeck(route.params.id),
enabled: () => !!route.params.id,
})
