查询键

在核心层面，TanStack Query 基于查询键（query keys）为你管理查询缓存。查询键在顶层必须是一个数组，它可以简单到只包含一个字符串的数组，也可以复杂到包含多个字符串和嵌套对象的数组。只要查询键能通过 JSON.stringify 进行序列化，并且对该查询的数据是唯一的，你就可以使用它！

简单的查询键

最简单的键形式是包含常量值的数组。这种格式适用于：

• 通用的列表/索引资源

• 非分层的资源

// 一个待办事项列表
useQuery({ queryKey: ['todos'], ... })

// 其他任何东西！
useQuery({ queryKey: ['something', 'special'], ... })

带变量的数组键

当一个查询需要更多信息来唯一描述其数据时，你可以使用一个包含字符串和任意数量可序列化对象的数组来描述它。这适用于：

• 分层或嵌套的资源

  • 通常会传入一个 ID、索引或其他原始值来唯一标识该项目

• 带有额外参数的查询

  • 通常会传入一个包含其他选项的对象

// 单个待办事项
useQuery({ queryKey: ['todo', 5], ... })

// 以“预览”格式显示的单个待办事项
useQuery({ queryKey: ['todo', 5, { preview: true }], ...})

// 一个“已完成”的待办事项列表
useQuery({ queryKey: ['todos', { type: 'done' }], ... })

查询键是确定性哈希的！

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

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', undefined, page, status], ...})

如果你的查询函数依赖于变量，请将其包含在查询键中

由于查询键唯一地描述了它们所获取的数据，因此它们应该包含你在查询函数中使用的任何会变化的变量。例如：

function Todos({ todoId }) {
  const result = useQuery({
    queryKey: ['todos', todoId],
    queryFn: () => fetchTodoById(todoId),
  })
}

请注意，查询键会作为你查询函数的依赖项。将依赖变量添加到查询键中，可以确保查询被独立缓存，并且在变量发生变化时，查询会自动重新获取（取决于你的 staleTime 设置）。有关更多信息和示例，请参阅 exhaustive-deps 部分。

进一步阅读

有关在大型应用程序中组织查询键的技巧，请查看社区资源中的 高效的 React Query 键，并查看 查询键工厂包。