TRPC React Query 中 useSuspenseQuery 的上下文传递问题解析

在 TRPC 与 React Query 的集成使用中，开发者发现了一个关于操作上下文传递的重要问题。本文将深入分析该问题的技术背景、产生原因以及解决方案。

问题现象

当开发者使用 TRPC 的 useSuspenseQuery 或 usePrefetchQuery 钩子时，通过 trpc.context 选项传递的操作上下文无法正确到达查询执行阶段。具体表现为：

const [data] = trpc.greeting.useSuspenseQuery(
  { name: 'client' },
  { trpc: { context: { hello: 'world' } } }
);

在 HTTP 链接的 headers 回调中，预期的 { hello: 'world' } 上下文变成了空对象 {}。

技术背景

TRPC 的 React Query 集成提供了多种查询钩子，包括常规查询、无限查询和 Suspense 查询等。这些钩子在内部都使用 React Query 的核心功能，但添加了 TRPC 特有的功能层。

操作上下文(Operation Context)是 TRPC 的一个重要概念，它允许在请求链路中传递额外的元数据，这些数据可以用于：

• 自定义 HTTP 头信息
• 控制请求行为（如取消逻辑）
• 传递认证信息
• 其他中间件需要的上下文数据

问题根源分析

通过对比 useSuspenseQuery 和 useSuspenseInfiniteQuery 的实现代码，可以发现关键差异：

在 useSuspenseInfiniteQuery 中，上下文被正确传递：

const actualOpts = {
  ...ssrOpts,
  trpc: {
    ...ssrOpts?.trpc,  // 正确传播上下文
    ...(shouldAbortOnUnmount ? { signal: queryFunctionContext.signal } : {}),
  },
};

而在 useSuspenseQuery 中，上下文被忽略：

const actualOpts = {
  trpc: {
    ...(shouldAbortOnUnmount ? { signal: queryFunctionContext.signal } : {}),
  },
  // 缺少了上下文传播
};

这种不一致导致了 useSuspenseQuery 无法正确传递开发者提供的操作上下文。

影响范围

该问题影响以下 TRPC 钩子：

• useSuspenseQuery
• usePrefetchQuery

而以下钩子工作正常：

• useSuspenseInfiniteQuery
• 常规的 useQuery

解决方案

修复方案相对直接，需要在 useSuspenseQuery 的实现中正确传播操作上下文：

const actualOpts = {
  ...opts,  // 传播所有选项
  trpc: {
    ...opts?.trpc,  // 传播上下文
    ...(shouldAbortOnUnmount ? { signal: queryFunctionContext.signal } : {}),
  },
};

开发者建议

对于遇到此问题的开发者，在官方修复发布前可以采取以下临时解决方案：

1. 使用常规 useQuery 替代 useSuspenseQuery
2. 创建自定义钩子包装 useSuspenseQuery，手动处理上下文传递
3. 如果上下文用于认证等关键功能，考虑使用全局拦截器替代

总结

TRPC 的 React Query 集成虽然强大，但在某些特定钩子实现上存在不一致性。这个问题提醒我们在使用新兴技术栈时，需要深入理解其实现细节，特别是在涉及请求链路和上下文传递的关键功能上。开发者社区通过发现和修复这类问题，共同推动了开源项目的成熟和稳定。