React Query中Promise作为查询键的注意事项

理解查询键的序列化机制

React Query作为一款优秀的状态管理库，其核心功能之一就是基于查询键(queryKey)进行数据缓存。然而，当开发者尝试将Promise对象直接作为查询键的一部分时，会遇到一个常见但容易被忽视的问题：所有不同的Promise对象最终都会被序列化为相同的空对象{}。

问题现象分析

在实际开发中，我们可能会编写类似下面的自定义Hook：

import { useQuery } from "@tanstack/react-query";

export const usePromise = <T>(promise: Promise<T>) => {
  return useQuery({
    queryKey: ["promise", promise],
    queryFn: () => promise,
  }).data;
};

这种情况下，无论传入什么Promise对象，React Query内部都会将它们序列化为{}，导致缓存失效。这是因为React Query默认要求查询键必须是可JSON序列化的数据结构。

技术原理深入

React Query对查询键的处理遵循以下原则：

1. 序列化要求：查询键需要能够被JSON.stringify正确处理，这是为了支持SSR、持久化存储等场景
2. 对象处理：对于普通对象，React Query会进行浅比较；但对于Promise这类特殊对象，序列化后会丢失其唯一性特征
3. 哈希机制：默认情况下，React Query不提供对象实例级别的哈希功能

解决方案推荐

官方推荐方案

React Query官方建议通过queryKeyHashFn来自定义哈希函数：

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      queryKeyHashFn: (key) => {
        // 自定义哈希逻辑
        return JSON.stringify(key, customReplacer);
      },
    },
  },
});

替代实现方案

如果确实需要使用Promise作为查询依据，可以考虑以下模式：

export const usePromise = <T>(promise: Promise<T>, id: string) => {
  return useQuery({
    queryKey: ["promise", id], // 使用唯一ID代替Promise本身
    queryFn: () => promise,
  }).data;
};

高级哈希方案

对于需要保持对象实例唯一性的场景，可以实现WeakMap为基础的ID生成器：

const createIdGenerator = () => {
  let counter = 0;
  const map = new WeakMap<WeakKey, number>();
  
  return (obj: WeakKey) => {
    if (!map.has(obj)) {
      map.set(obj, ++counter);
    }
    return map.get(obj)!;
  };
};

const getObjectId = createIdGenerator();

最佳实践建议

1. 避免直接使用非序列化对象：尽量不要将函数、Promise等不可序列化对象放入查询键
2. 使用唯一标识符：为动态内容提供稳定的ID或标识符
3. 考虑查询键设计：查询键应该反映数据的唯一性特征，而不仅仅是技术实现细节
4. 文档参考：详细阅读React Query文档中关于查询键序列化的说明

总结

React Query的查询键机制设计为可序列化结构是有其深层考虑的，主要是为了支持更广泛的用例和更好的可预测性。理解这一设计原则后，开发者可以通过合理的键设计和自定义哈希函数来满足各种复杂场景的需求，同时保持应用的性能和稳定性。