TanStack Lit Query 中 getDefaultQueryClient 完全解读：默认 QueryClient 的注册、歧义检测与返回值语义

TanStack Query 的 @tanstack/lit-query 为 Web Components / Lit 应用提供了服务端状态管理能力，其中的 getDefaultQueryClient() 是一个进程级（process-local）默认客户端查询函数：它不接收任何参数，返回当前已注册且唯一的默认 QueryClient；当没有注册任何客户端，或同一 JavaScript 上下文内注册了多个不同的客户端时，它会返回 undefined 而不是抛出异常。本文以 packages/lit-query/src/context.ts 及配套测试为事实依据，完整讲解该 API 的签名、底层引用计数实现、与 QueryClientProvider 的联动关系，以及在实际应用中它与 useQueryClient()、resolveQueryClient() 的取舍。

1. 函数签名与官方语义

getDefaultQueryClient 是 @tanstack/lit-query 公开导出的核心 Context 工具之一（见 包入口导出列表），其 TypeScript 类型签名非常简单：

function getDefaultQueryClient(): QueryClient | undefined;

该函数不接收任何参数，返回类型是 QueryClient | undefined。按照官方 API 参考文档（即本仓库 getDefaultQueryClient 参考）的说明，其返回值的判定规则为：

注册状态	返回值
恰好只有一个默认客户端被注册	返回该 QueryClient 实例
没有任何客户端被注册	返回 undefined
同时注册了多个（不同）客户端	返回 undefined

与那些直接抛错的辅助函数不同，getDefaultQueryClient 把“是否有默认值可用”作为返回值的一部分暴露给调用方——调用方需要自己检查 undefined 并决定后续行为。这意味着它适合被用于“条件性”的查询逻辑（例如：如果存在默认客户端就用它初始化某段代码，否则走降级路径），而不是“必须拿到客户端否则失败”的刚性场景。

2. 底层实现：模块级 Map + 引用计数

函数定义位于 packages/lit-query/src/context.ts 第 72 行，其完整实现如下：

const registeredClients = new Map<QueryClient, number>()
let defaultClient: QueryClient | undefined

export function registerDefaultQueryClient(client: QueryClient): void {
  registeredClients.set(client, (registeredClients.get(client) ?? 0) + 1)
  defaultClient = client
}

export function unregisterDefaultQueryClient(client: QueryClient): void {
  const count = registeredClients.get(client)
  if (count === undefined) {
    return
  }
  if (count > 1) {
    registeredClients.set(client, count - 1)
    return
  }
  registeredClients.delete(client)
  if (defaultClient !== client) {
    return
  }
  const remaining = [...registeredClients.keys()]
  defaultClient = remaining.at(-1)
}

export function getDefaultQueryClient(): QueryClient | undefined {
  if (registeredClients.size > 1) {
    return undefined
  }
  return defaultClient
}

从中可以看出三个关键实现事实：

1. 按实例而非按类型去重：registeredClients 是一个 Map<QueryClient, number>，以客户端实例对象为键，因此同一个 QueryClient 实例被多个 Provider 挂载只算一个“不同客户端”，而两个不同实例则算两个不同客户端。
2. 引用计数支持重复注册/释放：registerDefaultQueryClient 每次调用都让计数 +1 并刷新 defaultClient；unregisterDefaultQueryClient 则递减计数，只有当计数归零时才真正从 Map 中删除该实例，并在删除对象恰为当前 defaultClient 时，用 remaining.at(-1)（即最后仍注册的客户端）兜底作为新的默认值。
3. 歧义判定只看“不同实例的数量”：registeredClients.size > 1 即视为存在多个默认客户端、默认语义发生歧义，此时即便 defaultClient 变量仍指向某一实例，getDefaultQueryClient() 也坚持返回 undefined。

3. 谁在调用注册与反注册：QueryClientProvider 的自动接线

日常开发中你几乎不需要手动调用 registerDefaultQueryClient / unregisterDefaultQueryClient，因为 QueryClientProvider 会在自身的生命周期钩子里自动完成注册与反注册。

在 QueryClientProvider 生命周期实现 中：

• connectedCallback() 时调用 mountClient(client)：先执行 client.mount() 让查询客户端进入活跃状态，再执行 registerDefaultQueryClient(client)；
• disconnectedCallback() 时调用 unmountClient(this.mountedClient)：先 client.unmount()，再 unregisterDefaultQueryClient(client)；
• 当 Provider 的 client 属性在连接期间被换绑（willUpdate 分支），会先卸载旧客户端、再挂载并注册新客户端；
• 若已连接的 Provider 的 client 被置空（undefined），会先卸载已挂载客户端，并通过 ContextProvider.setValue(undefined) 通知消费者，最后抛出 "No QueryClient available" 错误。

因此，getDefaultQueryClient() 的有效生命周期与“Provider 处于连接状态”高度绑定：只要 Provider 还在 DOM 中，其 client 就一直处于注册状态；Provider 从 DOM 移除，client 随即被反注册。

另外值得注意的是，QueryClientProvider 在 @lit/context 体系中还承担着向下传递客户端的职责：它把 queryClientContext（context key 为 Symbol.for('tanstack-query-client')，见 context.ts 上下文 key 定义）通过 ContextProvider 提供给 DOM 树内的后代元素。也就是说，同一个客户端存在两条交付通道：

• 面向组件树的上下文通道：后代 controller 通过 ContextEvent 在组件树内就近解析到 provider 的 client（参见 BaseController 的上下文解析逻辑）；
• 面向命令式代码的进程级回退存储：即本文讨论的 registerDefaultQueryClient / getDefaultQueryClient 这套机制。

组件树内应优先使用前者；后者只是给“无法通过组件树拿 context”的命令式代码提供兜底。

4. getDefaultQueryClient 的两个重要消费者

在 @tanstack/lit-query 内部，getDefaultQueryClient 是另外两个公开 API 的基础实现单元。

4.1 useQueryClient()：把 undefined 转成抛出异常

useQueryClient 实现 完整代码如下：

export function useQueryClient(): QueryClient {
  const client = getDefaultQueryClient()
  if (client) {
    return client
  }
  if (registeredClients.size > 1) {
    throw createAmbiguousQueryClientError()
  }
  throw createMissingQueryClientError()
}

它的行为差异体现在错误消息的区分上：

• 没有任何 Provider 连接时抛出 'No QueryClient available. Pass one explicitly or render within QueryClientProvider.'；
• 存在多个不同 Provider（多客户端歧义）时抛出 'Multiple QueryClients are mounted. Pass one explicitly instead of relying on global QueryClient helpers.'。

两条错误消息常量定义于 context.ts 错误消息定义。换句话说，useQueryClient 底层复用了 getDefaultQueryClient 的“多客户端返回 undefined”语义，再根据 registeredClients.size 二次判断究竟是“缺失”还是“歧义”，进而给出精确的失败信息。

4.2 resolveQueryClient(explicit?)：显式优先的解析入口

resolveQueryClient 实现 只是一行：

export function resolveQueryClient(explicit?: QueryClient): QueryClient {
  return explicit ?? useQueryClient()
}

调用方可以传入显式 QueryClient，传入时永远优先返回显式实例（测试用例 "prefers an explicit client in resolveQueryClient" 验证了这一行为）；未传入时回退到 useQueryClient()，因此同样遵循“唯一默认、否则抛错”的规则。

4.3 推荐使用的判断流程

结合三个 API，推荐的命令式场景取值流程可以归纳为：

1. 已有明确实例 → 直接使用该实例，或交给 resolveQueryClient(explicit)；
2. 没有明确实例、且确认自己运行在唯一的 Provider 之下 → 使用 useQueryClient() 或 resolveQueryClient()，二者会在条件不满足时立刻抛错，便于尽早暴露配置错误；
3. 只是想做“有默认客户端就用、没有就算了”的探测式逻辑 → 用 getDefaultQueryClient()，它通过 undefined 表达“无默认值”，永远不会抛错。

5. 引用计数与歧义语义的测试验证

仓库配套测试 context-provider.test.ts 精确刻画了本文所述的各项语义，可作为理解行为边界的“可执行文档”：

• 注册 / 反注册联动：把一个 Provider 挂载进 document.body 后，useQueryClient() 与 resolveQueryClient() 都返回该 client；Provider 被移除后二者抛 "No QueryClient available"（第 35-50 行）。
• 同一实例多处挂载仍视为单个默认：两个 Provider 共享同一个 client 实例时，useQueryClient() 正常工作；先后移除两个 Provider 后，直到最后一个 Provider 断开注册才报缺失（第 57-80 行）——这正是 Map 引用计数设计要解决的场景。
• 多不同实例导致歧义：两个 Provider 分别持有 clientA、clientB 时，getDefaultQueryClient() 返回 undefined，useQueryClient() 与 resolveQueryClient() 抛出 /Multiple QueryClients are mounted/；移除 providerB 后唯一剩余的 clientA 恢复为默认（第 82-109 行）。
• Provider 生命周期严格性：Provider 换绑 client 时 mount/unmount 调用次数严格成对；连接期间的 client 被置空会先卸载再抛错，且随后 getDefaultQueryClient() 为 undefined（第 118-210 行）。

这些用例说明“进程级默认回退”是有意保守的设计——与其给出一个不可靠的猜测值，不如明确反馈缺失或歧义，把决策权交还给开发者。

6. 实用边界：何时该用、何时不该依赖它

官方指南 reactive-controllers-vs-hooks.md 对该回退机制给出了权威的边界建议，原文要点如下：

• 没有任何 Provider 连接：useQueryClient() 抛错；
• 恰好一个不同客户端连接：返回它；
• 同一 JavaScript 上下文内连接了多个不同客户端：useQueryClient() 与 resolveQueryClient() 抛错（歧义）。

并明确警告：多根节点、微前端、共享模块的测试套件、嵌套应用等场景不应依赖进程级回退。正确做法是：

1. 让 host-bound 的 controller 渲染在正确的 Provider 之下（组件树上下文解析天然正确，见 BaseController 上下文订阅）；
2. 或显式把 QueryClient 作为构造参数传给 controller / 传给 resolveQueryClient(explicit)；
3. 或在不同测试之间彻底断开/清理 Provider，避免跨用例的注册残留。

这些指导同样适用于 getDefaultQueryClient()：它是回退存储的“纯查询”入口，是探测进程级默认状态的安全手段，但不应成为跨边界传递客户端的主要方式。

7. 与安装/快速入门中的标准用法衔接

在实际 Lit 应用中，标准接入路径是（详见 Lit Query 安装指南 与 overview）：

import { html, LitElement } from 'lit'
import { QueryClient, QueryClientProvider } from '@tanstack/lit-query'

const queryClient = new QueryClient()

class AppQueryProvider extends QueryClientProvider {
  constructor() {
    super()
    this.client = queryClient
  }
}
customElements.define('app-query-provider', AppQueryProvider)

只要 app-query-provider 处于连接状态，以下两条命令式代码都能拿到同一个客户端：

import { getDefaultQueryClient, useQueryClient, resolveQueryClient } from '@tanstack/lit-query'

const viaProbe = getDefaultQueryClient()   // QueryClient | undefined，永不抛错
const viaStrict = useQueryClient()         // QueryClient，缺失/歧义时抛错
const viaExplicit = resolveQueryClient(myClient) // 永远优先 myClient

8. 小结：返回 undefined 本身就是一种有价值的信号

getDefaultQueryClient() 看起来只是 QueryClient | undefined 的一行签名，但它在 context.ts 中承载的是完整的“进程级默认客户端注册表”设计：registerDefaultQueryClient / unregisterDefaultQueryClient 负责带引用计数的注册与释放，QueryClientProvider 在连接生命周期内自动维护这套注册，而 getDefaultQueryClient 把“零注册”与“多注册歧义”两种情况统一折叠为 undefined 返回值，供上层 API 与业务代码灵活消费。

理解它的价值在于认清三条经验：

1. 它不抛错，适合做条件探测，而不是强约束取值的唯一入口；
2. 它区分实例而非注册次数，同一个实例挂载多处不会造成歧义，多个不同实例才会；
3. 它是为单一 Provider 环境设计的兜底查询，微前端、多根节点等复杂拓扑应使用组件树上下文或显式传参，而不是依赖进程级默认值。