Apollo Client 中 Suspense 查询错误缓存机制解析

前言

在使用 Apollo Client 的 React Suspense 功能时，开发者可能会遇到一个特殊现象：当查询抛出错误后，即使设置了 no-cache 获取策略，错误结果仍会被缓存。本文将深入分析这一现象背后的机制，并探讨其设计原理和应对策略。

核心问题分析

现象描述

当使用 useSuspenseQuery 进行数据查询时，如果服务器返回错误：

1. 首次访问页面时，查询失败并显示错误
2. 离开页面后再次返回时，不会重新发起请求
3. 错误结果被复用，没有新的服务器调用

关键发现

这一现象与 Apollo Client 的两个独立缓存系统有关：

1. 常规数据缓存：由 InMemoryCache 管理，受 fetchPolicy 控制
2. Suspense 专用缓存：独立于数据缓存，专门用于 Suspense 场景

技术原理详解

Suspense 缓存机制

Apollo Client 为 Suspense 功能实现了一个特殊的缓存层，其主要特点包括：

1. 查询引用(QueryRef)缓存：保存了包含错误结果的 Promise 对象
2. 自动清理机制：默认30秒后自动清理缓存项
3. 独立于数据缓存：不受常规 fetchPolicy 设置影响

设计考量

这种设计主要基于以下考虑：

1. Suspense 行为一致性：确保组件在短时间内重新挂载时保持相同状态
2. 错误边界处理：避免在短时间内重复触发错误边界
3. 性能优化：防止频繁错误查询导致的性能问题

解决方案与实践建议

测试场景处理

在单元测试环境中，可以采用以下策略：

1. 独立客户端实例：为每个测试创建新的 Apollo Client 实例
2. 手动清理缓存：通过内部符号访问并清理 Suspense 缓存
3. 调整超时设置：缩短 autoDisposeTimeoutMs 参数

生产环境建议

1. 合理设置超时：根据业务需求调整自动清理时间
2. 错误处理策略：在错误边界中实现重试逻辑
3. 组件设计：考虑使用键(key)属性强制重新加载组件

深入理解

技术细节

Apollo Client 内部使用 Symbol 存储 Suspense 缓存引用，开发者可以通过特定方式访问：

const suspenseCacheSymbol = Symbol.for('apollo.suspenseCache');

最佳实践

1. 避免共享客户端：特别是在测试场景中
2. 理解缓存层次：区分数据缓存和 Suspense 缓存
3. 合理设置参数：根据场景调整 autoDisposeTimeoutMs

总结

Apollo Client 的 Suspense 实现采用了独特的缓存策略，这种设计虽然在某些场景下可能带来困惑，但实际上是经过深思熟虑的架构决策。理解这一机制有助于开发者更好地构建健壮的应用程序，特别是在错误处理和测试场景中。通过合理配置和适当的工作区，可以有效地管理这一行为，确保应用符合预期。