React Query 在 Next.js 中服务端数据获取的实践与问题解析

前言

在现代前端开发中，数据获取是一个核心话题。React Query 作为一款强大的数据同步库，与 Next.js 的服务端渲染能力结合使用时，能够提供优秀的用户体验。本文将深入探讨 React Query 在 Next.js 应用中实现服务端数据获取的正确方式，以及开发过程中可能遇到的典型问题。

服务端数据获取的基本原理

React Query 与 Next.js 结合使用时，通常遵循以下流程：

1. 服务端预取数据：在页面渲染前，通过 prefetchQuery 方法获取数据
2. 创建 QueryClient 实例：为每个请求创建独立的 QueryClient 实例
3. 数据脱水：将预取的数据注入到客户端
4. 客户端水合：客户端接管后继续管理数据状态

这种模式理论上应该完全在服务端完成数据获取，客户端直接使用预取的数据而不需要额外请求。

常见问题现象

许多开发者会遇到一个看似矛盾的现象：明明按照官方文档实现了服务端数据获取，但在 Chrome 开发者工具的 Network 面板中仍然能看到客户端发起的 API 请求。具体表现为：

1. 页面加载后，客户端仍然发起数据请求
2. 请求状态显示为 200 OK (from disk cache)
3. 在 StackBlitz 等在线编辑器中问题更加明显

问题根源分析

经过深入探究，这种现象主要由以下几个因素导致：

1. 缓存时效性设置：默认的 staleTime 配置为 1 分钟，超过时效后客户端会自动重新验证数据
2. 浏览器缓存行为：API 响应头中的 Cache-Control 指示浏览器可以重用缓存数据
3. 开发环境特殊性：本地开发环境和在线编辑器存在证书验证等问题

解决方案与实践建议

1. 调整缓存时效策略

function makeQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: Infinity, // 设置为无限大避免客户端重新请求
      },
    },
  });
}

2. 处理开发环境证书问题

在本地开发时，可能会遇到自签名证书问题，可以通过配置 HTTPS 代理解决：

import { Agent } from 'https';

export async function fetchPokemon() {
  const agent = new Agent({
    keepAlive: true,
    timeout: 5000,
    rejectUnauthorized: false,
  });
  
  const response = await axios.get("https://pokeapi.co/api/v2/pokemon/25", {
    httpsAgent: agent,
  });

  return response.data;
}

3. 使用 useSuspenseQuery 替代方案

考虑使用 useSuspenseQuery 可以更早地暴露潜在问题，如证书验证错误等：

const { data } = useSuspenseQuery({
  queryKey: ['pokemon'],
  queryFn: fetchPokemon,
});

最佳实践总结

1. 明确区分环境：生产环境和开发环境采用不同的缓存策略
2. 合理设置 staleTime：根据业务需求平衡数据新鲜度和性能
3. 全面错误处理：特别注意开发环境下的证书和网络问题
4. 监控网络行为：定期检查实际网络请求是否符合预期

结语

React Query 与 Next.js 的结合为开发者提供了强大的数据管理能力，但需要深入理解其工作原理才能充分发挥优势。通过本文的分析和建议，开发者可以更好地实现真正的服务端数据获取，避免常见的陷阱，构建更高效的前端应用。