Query Keys

Query Keys

在其核心，TanStack Query 基于 query keys 为您管理 query 缓存。Query keys 必须是顶级的数组，并且可以像包含单个字符串的数组一样简单，或者像包含许多字符串和嵌套对象的数组一样复杂。只要 query key 是可序列化的，并且对于 query 的数据是唯一的，您就可以使用它！

简单的 Query Keys

key 最简单的形式是包含常量值的数组。此格式对于以下情况很有用

通用列表/索引资源
非层级资源

tsx

// A list of todos
useQuery({ queryKey: ['todos'], ... })

// Something else, whatever!
useQuery({ queryKey: ['something', 'special'], ... })

// A list of todos
useQuery({ queryKey: ['todos'], ... })

// Something else, whatever!
useQuery({ queryKey: ['something', 'special'], ... })

带有变量的数组 Keys

当 query 需要更多信息来唯一描述其数据时，您可以使用包含字符串和任意数量可序列化对象的数组来描述它。这对于以下情况很有用

层级或嵌套资源
- 通常传递 ID、索引或其他原始值来唯一标识项目
带有附加参数的 Queries
- 通常传递附加选项的对象

tsx

// An individual todo
useQuery({ queryKey: ['todo', 5], ... })

// An individual todo in a "preview" format
useQuery({ queryKey: ['todo', 5, { preview: true }], ...})

// A list of todos that are "done"
useQuery({ queryKey: ['todos', { type: 'done' }], ... })

// An individual todo
useQuery({ queryKey: ['todo', 5], ... })

// An individual todo in a "preview" format
useQuery({ queryKey: ['todo', 5, { preview: true }], ...})

// A list of todos that are "done"
useQuery({ queryKey: ['todos', { type: 'done' }], ... })

Query Keys 是确定性地哈希处理的！

这意味着无论对象中键的顺序如何，以下所有 query 都被认为是相等的

tsx

useQuery({ queryKey: ['todos', { status, page }], ... })
useQuery({ queryKey: ['todos', { page, status }], ...})
useQuery({ queryKey: ['todos', { page, status, other: undefined }], ... })

useQuery({ queryKey: ['todos', { status, page }], ... })
useQuery({ queryKey: ['todos', { page, status }], ...})
useQuery({ queryKey: ['todos', { page, status, other: undefined }], ... })

但是，以下 query keys 不相等。数组项顺序很重要！

tsx

useQuery({ queryKey: ['todos', status, page], ... })
useQuery({ queryKey: ['todos', page, status], ...})
useQuery({ queryKey: ['todos', undefined, page, status], ...})

useQuery({ queryKey: ['todos', status, page], ... })
useQuery({ queryKey: ['todos', page, status], ...})
useQuery({ queryKey: ['todos', undefined, page, status], ...})

如果您的 query 函数依赖于变量，请将其包含在您的 query key 中

由于 query keys 唯一地描述了它们正在获取的数据，因此它们应包含您在 query 函数中使用的任何更改的变量。例如

function useTodos(todoId) {
  const queryKey = ['todos', todoId]
  return useQuery({
    queryKey,
    queryFn: () => fetchTodoById(todoId.value),
  })
}

function useTodos(todoId) {
  const queryKey = ['todos', todoId]
  return useQuery({
    queryKey,
    queryFn: () => fetchTodoById(todoId.value),
  })
}

请注意，query keys 充当您的 query 函数的依赖项。将依赖变量添加到您的 query key 将确保 queries 被独立缓存，并且任何时候变量发生更改，queries 将会自动重新获取（取决于您的 staleTime 设置）。有关更多信息和示例，请参阅 exhaustive-deps 部分。

进一步阅读

有关在大型应用程序中组织 Query Keys 的技巧，请查看 Effective React Query Keys 并查看来自社区资源的 Query Key Factory Package。