Apollo Client 3.8版本中onCompleted回调的重大变更解析

在Apollo Client 3.8版本中，开发团队对onCompleted回调的行为进行了重大调整，这一变更对许多现有应用的逻辑产生了深远影响。本文将深入剖析这一变更的技术细节、背后的设计考量以及开发者应如何应对。

行为变更的核心内容

在3.8版本之前，onCompleted回调会在以下情况下触发：

1. 查询首次完成时
2. 任何导致缓存更新的操作发生时（包括其他组件触发的refetch）
3. 网络请求返回时（无论notifyOnNetworkStatusChange设置如何）

3.8版本对此进行了重大调整：

1. 缓存更新不再触发：当其他操作（如mutation）导致缓存更新时，onCompleted不再自动触发
2. 网络请求条件化触发：只有设置notifyOnNetworkStatusChange: true时，后续网络请求才会触发onCompleted

变更的技术背景

这一变更源于Apollo Client内部ObservableQuery实例的管理方式。在3.7及更早版本中，通过refetchQueries选项触发的查询会创建全新的ObservableQuery实例，与原始查询实例并无直接关联。onCompleted的触发实际上是缓存更新的副作用，而非设计上的功能。

开发团队认为这种"意外工作"的行为不够可靠，因此在3.8版本中进行了修正，使回调行为更加明确和可控。

对现有应用的影响

这一变更主要影响以下几类场景：

1. 状态管理：许多应用在onCompleted中设置组件状态，当缓存更新时这些状态可能变得不同步
2. 级联查询：依赖onCompleted触发后续查询的"瀑布流"式数据获取模式
3. UI控制：基于查询结果自动展开/折叠UI元素的逻辑

推荐的迁移策略

1. 派生状态替代方案

对于在onCompleted中设置状态的常见模式，推荐使用派生值：

// 不推荐的方式
const [count, setCount] = useState(0);
useQuery(query, {
  onCompleted: (data) => setCount(data.items.length)
});

// 推荐的方式
const { data } = useQuery(query);
const count = data?.items?.length || 0;

派生值的优势在于：

• 自动保持与缓存同步
• 减少不必要的状态更新
• 代码更简洁

2. 复杂逻辑处理

对于需要在数据变化时执行复杂逻辑的场景，可以使用useEffect：

const { data } = useQuery(query, { notifyOnNetworkStatusChange: true });

useEffect(() => {
  if (data) {
    // 执行数据变化时的逻辑
  }
}, [data]);

3. 查询编排优化

对于级联查询场景，建议：

• 使用useLazyQuery手动控制查询时机
• 考虑GraphQL的@defer指令实现渐进式加载
• 重构为并行查询模式

设计理念的演进

这一变更反映了Apollo Client团队对API设计理念的演进：

1. 明确性：回调触发条件更加明确和可预测
2. 性能优化：减少不必要的回调执行
3. 状态管理简化：鼓励使用响应式数据而非命令式更新

最佳实践建议

1. 避免在回调中设置状态：这容易导致状态不同步
2. 谨慎使用notifyOnNetworkStatusChange：仅在需要跟踪加载状态时启用
3. 充分利用缓存：直接使用缓存数据而非复制到本地状态
4. 考虑使用Fragment：细粒度地订阅数据变化

总结

Apollo Client 3.8对onCompleted的变更是框架向更健壮、更可预测方向发展的必要调整。虽然短期内可能需要开发者调整现有代码，但长期来看，这种明确的行为定义将带来更稳定的应用表现和更简洁的代码结构。理解这一变更背后的设计理念，将帮助开发者更好地利用Apollo Client构建现代化的数据驱动应用。