Apollo Client中refetchQueries的DocumentNode引用比较问题解析

问题背景

在Apollo Client 3.x版本中，开发者在使用refetchQueries功能时可能会遇到一个隐蔽但影响较大的问题：当直接传递DocumentNode对象作为参数时，查询重取的执行会出现不一致的情况。这个问题特别容易在使用GraphQL Code Generator生成的客户端代码时出现。

问题本质

问题的核心在于Apollo Client内部对DocumentNode对象的比较机制。在QueryManager类的getObservableQueries方法中，系统会创建一个以查询名称或DocumentNode为键的Map结构。当检查需要重取的查询时，对于DocumentNode类型的键，Apollo Client采用的是严格的引用比较(reference equality)而非值比较(value equality)。

这意味着即使两个DocumentNode对象在结构上完全一致，只要它们不是同一个内存引用，就会被视为不同的查询。这种设计导致了以下现象：

• 在部分场景下功能正常（当使用同一个DocumentNode引用时）
• 在其他场景下会失败并显示警告"Unknown query requested in refetchQueries options.include array"（当使用结构相同但引用不同的DocumentNode时）

技术细节分析

在底层实现中，QueryManager处理refetchQueries参数时会经历以下关键步骤：

1. 创建一个queryNamesAndDocs的Map结构，键可以是查询名称(string)或DocumentNode对象
2. 遍历传入的include数组（即refetchQueries参数）来填充这个Map
3. 检查当前活跃的查询是否匹配Map中的键

问题特别出现在对DocumentNode的处理上。系统会先对原始文档应用DocumentTransform转换，然后将转换后的文档对象直接作为Map的键存储。在后续比较时，使用的是JavaScript严格的===操作符进行引用比较。

问题复现与验证

开发者可以通过以下方式验证这个问题：

// 这会失败，因为创建了新的DocumentNode引用
await mutation({
  variables: {},
  refetchQueries: [JSON.parse(JSON.stringify(SomeQueryDocumentNode))]
});

而以下方式可以正常工作：

// 直接使用原始DocumentNode引用
await mutation({
  variables: {},
  refetchQueries: [SomeQueryDocumentNode]
});

解决方案探讨

针对这个问题，Apollo Client团队和社区讨论了多种解决方案：

1. 使用查询名称替代DocumentNode： 通过getOperationName工具函数提取查询名称作为refetchQueries参数。这种方法简单可靠，但无法处理匿名查询。

2. 基于文档字符串的比较： 使用GraphQL的print函数将DocumentNode转换为字符串形式作为Map的键。Apollo Client内部已经实现了带缓存的print函数，性能影响较小。这种方法既能保持现有功能，又能解决引用比较的问题。

3. 文档转换缓存优化： 确保DocumentTransform的结果被正确缓存，避免对相同输入产生不同引用的输出。这需要仔细检查缓存配置，特别是使用自定义缓存实现时。

最佳实践建议

对于开发者而言，在当前版本中可以采取以下最佳实践：

1. 优先使用查询名称而非DocumentNode作为refetchQueries参数
2. 如果必须使用DocumentNode，确保在整个应用中保持对同一引用的使用
3. 避免在运行时动态创建或修改DocumentNode对象
4. 考虑使用Apollo Client提供的工具函数进行查询名称提取

总结

这个问题揭示了Apollo Client内部实现中一个重要的设计考量：在复杂的前端应用中，特别是在使用了代码分割、热模块替换等现代前端技术的情况下，保证对象引用的一致性可能比预期更加困难。Apollo Client团队建议的未来方向是采用基于文档字符串的比较方案，这既能保持现有功能的完整性，又能解决引用比较带来的问题。

对于开发者来说，理解这一底层机制有助于更好地使用refetchQueries功能，避免在实际开发中遇到难以调试的不一致问题。同时，这也提醒我们在设计类似的API时，需要考虑引用比较可能带来的潜在问题。