Pinia-Colada 项目中的 Query Keys 详解

Pinia-Colada 项目中的 Query Keys 详解

什么是 Query Keys

在 Pinia-Colada 项目中，Query Keys（查询键）是用于标识缓存中查询的唯一标识符。它是查询配置中除了 query 函数外最重要的属性，和 query 一样都是必填项。

Query Keys 的核心作用

Query Keys 主要有以下作用：

1. 唯一标识缓存中的查询
2. 管理查询之间的层级关系
3. 支持查询的自动失效和更新
4. 提供类型安全支持

静态 Query Keys

静态 Query Keys 是最简单的形式，它是一个可序列化属性的数组：

<script setup lang="ts">
import { useQuery } from '@pinia/colada'

const { state } = useQuery({
  key: ['products'],
  query: () => getProducts(),
})
</script>

这种形式适用于调用固定端点的查询，如 /api/products 或全局资源如用户信息。

动态 Query Keys

动态 Query Keys 依赖于响应式变量（如 ref、computed 或路由参数）：

<script setup lang="ts">
import { useQuery } from '@pinia/colada'
import { useRoute } from 'vue-router'

const route = useRoute()
const { state } = useQuery({
  key: () => ['products', route.params.id],
  query: () => getProductById(route.params.id),
})
</script>

重要提示：确保 Query Key 依赖于 query 函数中使用的所有变量，这是保证查询正确缓存和失效的关键。

Query Keys 的层级结构

Query Keys 的强大之处在于它们的层级结构特性。通过嵌套键可以创建查询的层次结构：

// 获取包含所有详细信息的商品
useQuery({
  key: () => ['products', productId.value],
  query: () => getProductById(productId.value),
})

// 获取适合搜索的商品摘要
useQuery({
  key: () => ['products', productId.value, { searchResult: true }],
  query: () => getProductSummaryById(productId.value),
})

这种结构允许我们一次性使特定商品的所有相关数据失效：

queryCache.invalidateQueries({ key: ['products', productId.value] })

管理 Query Keys（键工厂）

对于大型项目，建议使用键工厂模式来管理 Query Keys：

export const PRODUCT_QUERY_KEYS = {
  root: ['products'] as const,
  byId: (id: string) => [...PRODUCT_QUERY_KEYS.root, id] as const,
  byIdWithDetails: (id: string) => 
    [...PRODUCT_QUERY_KEYS.byId(id), { details: true }] as const,
}

键工厂的优势：

1. 避免拼写错误
2. 保持层级结构
3. 便于未来修改
4. 提高代码可维护性

类型化的 Query Keys

Pinia-Colada 提供了强大的类型支持：

const productQuery = defineQueryOptions({
  key: ['products', 'list'],
  query: () => getProductList(),
})

const queryCache = useQueryCache()
const productList = queryCache.getQueryData(productQuery.key)

对于动态键，可以使用函数形式：

const productByIdQuery = defineQueryOptions((id: string) => ({
  key: ['products', id],
  query: () => getProductById(id),
}))

最佳实践建议

1. 始终使用键工厂模式管理 Query Keys
2. 保持键的结构化和层次化
3. 使用 defineQueryOptions 获取类型安全
4. 确保键包含查询函数中使用的所有变量
5. 对于简单键，考虑重构为键工厂模式

通过遵循这些实践，可以构建出既健壮又易于维护的查询系统，充分利用 Pinia-Colada 提供的强大功能。