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

概述

在使用TanStack Query进行数据管理时，开发者可能会遇到一个常见但容易被忽视的问题：将Promise对象直接作为查询键(queryKey)的一部分。本文将通过一个典型场景分析这个问题，并探讨正确的解决方案。

问题现象

考虑以下自定义Hook的实现：

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

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

当开发者尝试使用不同的Promise调用此Hook时，会发现TanStack Query将所有Promise都视为相同的键{}，导致缓存结果被错误地复用。

原因分析

TanStack Query默认要求查询键必须是JSON可序列化的对象。这是出于以下设计考虑：

1. 跨环境传输：查询键需要能够在SSR(服务器端渲染)时通过网络传输
2. 持久化存储：查询键需要能够被存储到localStorage等持久化介质中
3. 一致性保证：确保在不同环境下相同的查询能够得到相同的结果

Promise对象作为JavaScript中的特殊对象，无法被简单地序列化。当TanStack Query尝试将包含Promise的查询键序列化时，最终会得到一个空对象{}，导致不同的Promise都被视为相同的查询键。

解决方案

1. 避免在查询键中使用Promise

最直接的解决方案是避免在查询键中使用Promise对象。可以将Promise转换为其他可序列化的标识符：

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

2. 自定义查询键哈希函数

对于高级用例，可以提供一个自定义的queryKeyHashFn函数：

const queryClient = new QueryClient({
  queryKeyHashFn: (key) => {
    // 自定义哈希逻辑
    return JSON.stringify(key, (_, value) => {
      if (value instanceof Promise) {
        // 为Promise生成唯一标识
        return `promise_${generateUniqueIdForPromise(value)}`;
      }
      return value;
    });
  },
});

3. 使用WeakMap跟踪Promise

如提问者建议，可以使用WeakMap为Promise生成唯一ID：

const promiseIds = new WeakMap<Promise<unknown>, number>();
let idCounter = 0;

function getPromiseId(promise: Promise<unknown>): number {
  if (!promiseIds.has(promise)) {
    promiseIds.set(promise, ++idCounter);
  }
  return promiseIds.get(promise)!;
}

最佳实践

1. 保持查询键简单可序列化：尽量使用基本类型(string, number等)或简单对象作为查询键
2. 明确区分不同查询：为每个独立的异步操作提供明确的标识符
3. 考虑查询键的稳定性：确保相同逻辑的查询在不同环境下生成相同的键
4. 文档查阅：在使用特殊对象作为查询键前，仔细阅读相关文档

总结

TanStack Query对查询键的序列化要求是其设计哲学的一部分，确保了框架在各种场景下的可靠性和一致性。理解这一设计决策有助于开发者避免常见的陷阱，构建更健壮的应用程序。当需要在查询键中使用复杂对象时，应当考虑提供适当的序列化策略或使用替代标识方案。