TanStack Query 中 initialData 在 ensureQueryData 中的行为解析与优化建议

背景介绍

在使用 TanStack Query 进行数据管理时，ensureQueryData 是一个常用的 API，它用于确保查询数据存在于缓存中。开发者经常需要配合 initialData 选项来实现缓存预填充（cache seeding）策略，特别是在实现"拉取式"（pull approach）数据预加载时。

问题现象

当开发者使用 ensureQueryData 并设置 initialData 时，即使提供了有效的初始数据（包括 undefined），该 API 仍然会触发网络请求。这与开发者预期的行为不符——他们期望当提供 initialData 时，系统应该直接使用这些数据填充缓存，而跳过不必要的网络请求。

技术原理分析

在 TanStack Query 的设计中，initialData 的本意是作为查询的初始状态，通常用于以下场景：

1. 从服务器渲染（SSR）传递数据到客户端
2. 从其他查询结果中派生数据
3. 提供回退数据以避免加载状态闪烁

ensureQueryData 的设计初衷是确保数据存在于缓存中，如果不存在则获取。当前实现中，它没有充分考虑 initialData 的语义，导致无论是否提供初始数据都会发起请求。

解决方案建议

对于需要实现缓存预填充的场景，开发者可以考虑以下临时解决方案：

1. 先检查缓存再决定是否调用 ensureQueryData：

const cachedData = queryClient.getQueryData(queryKey);
if (!cachedData) {
  await queryClient.ensureQueryData({
    ...query,
    initialData: findInPages(...),
  });
}

2. 直接使用 setQueryData 设置初始数据：

if (!queryClient.getQueryData(queryKey)) {
  queryClient.setQueryData(queryKey, initialData);
}

最佳实践

在等待官方修复的同时，建议开发者：

1. 明确区分"必须有数据"和"可以接受初始数据"的场景
2. 对于关键数据，仍然保持网络请求以确保数据新鲜度
3. 对于可以接受初始数据的场景，采用上述变通方案
4. 在 TypeScript 中明确处理 initialData 为 undefined 的情况

总结

这个问题揭示了 API 设计中对边界情况考虑的重要性。TanStack Query 团队已经确认这是一个需要修复的问题，开发者可以关注后续版本更新。在此期间，理解底层原理并采用适当的变通方案，可以保证应用既保持性能又不失数据一致性。