解析 TanStack Query 的 ‘Structural Sharing’：它如何确保在 API 返回相同数据时保持 React 引用不变？

解析 TanStack Query 的 ‘Structural Sharing’：如何确保 API 返回相同数据时保持 React 引用不变

各位同仁，欢迎来到今天的技术讲座。今天我们将深入探讨 TanStack Query（以前称为 React Query）中的一个强大而微妙的特性：结构化共享 (Structural Sharing)。这个特性对于构建高性能、响应迅速的 React 应用至关重要，因为它直接解决了在数据获取场景中，React 应用中普遍存在的“引用相等性”问题。

在 React 的世界里，引用相等性是性能优化的基石。当组件的 props 或 state 发生变化时，React 会重新渲染。然而，如果一个 prop 的值在内容上是相同的，但引用却变了，React 仍然会认为它是一个新的值，并触发不必要的渲染。结构化共享正是为了解决 API 数据源的这一痛点而设计的。

1. React 中的引用相等性问题：性能优化的基石与陷阱

在深入结构化共享之前，我们必须首先理解为什么引用相等性在 React 中如此重要。React 的渲染机制依赖于对 props 和 state 的浅层比较来决定是否需要重新渲染一个组件。

1.1 为什么引用相等性至关重要？

考虑以下 React 优化机制：

• React.memo (HOC): 用于函数组件，如果其 props 在浅层比较后没有变化，则跳过渲染。
• shouldComponentUpdate (Class Component): 开发者可以手动实现逻辑来决定是否重新渲染。
• PureComponent (Class Component): 自动实现了一个浅层比较的 shouldComponentUpdate。
• useMemo 和 useCallback (Hooks): 用于缓存计算结果或函数实例，只有当其依赖项发生变化时才重新计算。

所有这些优化机制都基于一个核心前提：它们通过比较当前值和上一个值的引用来判断其是否“相同”。如果引用不同，即使底层数据内容一模一样，它们也会被认为是“不同”的，从而触发重新计算或重新渲染。

示例：不必要的渲染

假设我们有一个父组件 ParentComponent 和一个子组件 ChildComponent。ChildComponent 使用 React.memo 进行了优化。

import React, { useState, useEffect, useMemo } from 'react';

// ChildComponent 仅在其 props 改变时才渲染
const ChildComponent = React.memo(({ user }) => {
  console.log('ChildComponent rendered', user);
  return (
    <div>
      <h3>User Details</h3>
      <p>ID: {user.id}</p>
      <p>Name: {user.name}</p>
    </div>
  );
});

function ParentComponent() {
  const [count, setCount] = useState(0);
  const [userData, setUserData] = useState({ id: 1, name: 'Alice' });

  useEffect(() => {
    // 模拟每隔2秒更新一次父组件的状态，但userData内容不变
    const interval = setInterval(() => {
      setCount(prev => prev + 1);
      // 每次都创建一个新的对象，即使内容相同
      setUserData({ id: 1, name: 'Alice' }); 
    }, 2000);
    return () => clearInterval(interval);
  }, []);

  // 假设我们想要缓存user对象，但如果setUserData每次都创建新对象，这个useMemo就没用
  const memoizedUser = useMemo(() => userData, [userData]); 

  return (
    <div>
      <h1>Parent Component</h1>
      <p>Count: {count}</p>
      <button onClick={() => setCount(prev => prev + 1)}>Increment Count</button>
      <ChildComponent user={memoizedUser} />
    </div>
  );
}

export default ParentComponent;

在这个例子中，即使 userData 的内容 ({ id: 1, name: 'Alice' }) 始终没有变化，setUserData 每次都被调用时，都会创建一个全新的 JavaScript 对象。这意味着 userData 的引用每次都会改变。

因此：

1. memoizedUser 的依赖项 userData 每次都会被认为是不同的，导致 useMemo 每次都返回一个新的对象引用。
2. ChildComponent 的 user prop 每次都会收到一个具有新引用的对象，即使其内部属性完全相同。
3. React.memo 的浅层比较会失败，导致 ChildComponent 在每次父组件渲染时都重新渲染，尽管它的实际内容并未改变。

这便是“引用相等性问题”在 React 中的典型表现：不必要的渲染浪费了 CPU 资源，并可能导致 UI 闪烁或其他性能问题。在数据获取场景中，这个问题尤为突出，因为 API 响应往往是新的对象或数组。

1.2 TanStack Query 如何介入？

TanStack Query 是一款强大的数据管理库，它抽象了数据获取、缓存、同步和更新等复杂逻辑。它的核心能力之一就是智能地管理缓存数据。而结构化共享正是其缓存管理策略中的一个关键组成部分，旨在确保即使 API 返回的数据在内容上与缓存数据相同，也能尽可能地保持引用不变，从而与 React 的优化机制完美协同。

2. TanStack Query 的缓存与数据管理基础

在理解结构化共享的具体实现之前，我们先回顾一下 TanStack Query 的数据管理模型。

2.1 查询 (Queries) 与缓存 (Cache)

TanStack Query 的核心是“查询”。一个查询由一个唯一的 queryKey 和一个 queryFn（一个异步函数，用于实际获取数据）定义。

const queryClient = new QueryClient();

// 定义一个查询
queryClient.fetchQuery({
  queryKey: ['todos', 1],
  queryFn: async () => {
    const response = await fetch('/api/todos/1');
    return response.json();
  },
});

当 queryFn 成功获取数据后，这些数据会根据 queryKey 存储在 Query Cache 中。

2.2 查询的生命周期与状态

一个查询可以处于多种状态：

• fetching: 正在进行数据获取。
• stale: 数据已过期，可能需要重新获取（默认立即过期）。
• fresh: 数据是新鲜的，在 staleTime 期间内不会触发重新获取。
• inactive: 没有组件在使用这个查询，但数据仍保留在缓存中。
• evicted: 数据已从缓存中清除。

两个关键的时间参数：

• staleTime: 数据被视为新鲜的时间。在此期间，useQuery 会立即返回缓存数据而不会触发后台重新获取。默认为 0。
• cacheTime: 数据从不活跃状态到被垃圾回收的时间。默认为 5 * 60 * 1000 (5分钟)。

2.3 重新获取 (Refetching) 机制

TanStack Query 在多种情况下会触发数据的重新获取：

• 组件挂载时（如果数据是 stale）。
• 窗口重新获得焦点时 (refetchOnWindowFocus)。
• 网络重新连接时 (refetchOnReconnect)。
• 手动调用 queryClient.invalidateQueries 或 queryClient.refetchQueries。
• 调用 useQuery 返回的 refetch 函数。

每次重新获取都会调用 queryFn，并从 API 获取最新的数据。如果新获取的数据与缓存中的数据不同，缓存将被更新，从而触发使用该数据的组件重新渲染。

2.4 结构化共享要解决的问题

问题在于：当一个查询重新获取数据时，即使 API 返回的数据在内容上与缓存中的数据完全相同，queryFn 也会返回一个新的对象引用。

如果没有结构化共享，TanStack Query 就会简单地用这个新的对象引用替换掉缓存中的旧引用。这将导致：

1. useQuery 返回的 data 引用发生变化。
2. 所有依赖于 data 的 React 组件（特别是使用了 React.memo 或 useMemo 的组件）都会因为 data 引用的变化而重新渲染，即使它们所展示的实际内容没有任何改变。

这正是我们在 Section 1 中看到的“不必要的渲染”问题在数据获取场景中的体现。结构化共享应运而生，作为 TanStack Query 内部的一个智能优化机制，专门解决这一挑战。

3. 理解 ‘Structural Sharing’：保持引用不变的奥秘

结构化共享是 TanStack Query 的一个默认行为，它在数据重新获取后，将新数据与旧数据进行智能比较，以尽可能保持引用不变。

3.1 定义与核心思想

结构化共享 (Structural Sharing) 是指在更新复杂数据结构时，通过深度比较新旧数据，只替换发生实际变化的部分，而未变化的部分则继续沿用旧的引用。这意味着，如果 API 返回的数据与缓存中的数据在内容上完全一致，那么 useQuery 将会返回与之前完全相同的 data 引用。即使只有数据结构中的某个深层嵌套属性发生了变化，而其他部分保持不变，那些不变的部分也将保留其原有的引用。

核心思想：最小化引用变更，从而最小化 React 的重新渲染。

3.2 为什么对 React 如此关键？

回到我们之前讨论的 React.memo 和 useMemo：

• 当 useQuery 返回的 data 引用保持不变时，React.memo 包裹的子组件将不会因为父组件的重新渲染而重新渲染（前提是其他 props 也保持不变）。
• useMemo 和 useCallback 的依赖项（如果包含 data 或其深层属性）将不会失效，从而有效避免不必要的计算。

结构化共享使得 React 的各种性能优化手段能够真正发挥作用，因为它为这些优化提供了一个稳定的数据引用基础。

3.3 结构化共享的工作原理 (概念层面)

当 TanStack Query 的 queryFn 成功返回新数据后，它不会简单地用新数据替换旧数据。相反，它会执行以下逻辑：

1. 获取旧数据: 从缓存中取出与当前 queryKey 关联的旧数据。
2. 深度比较: 对新旧数据进行递归的深度比较。这个比较不仅仅是检查值是否相等，更重要的是检查数据结构（对象、数组、原始值）。
3. 构建新数据结构 (共享引用):
   • 如果新旧数据是原始类型（字符串、数字、布尔值、null、undefined），并且它们的值相等，则直接使用旧数据的值。
   • 如果新旧数据是对象：
     • 它会遍历新对象的所有属性。
     • 对于每个属性，它会递归地比较新旧属性的值。
     • 如果某个属性的值（包括深层嵌套的值）与旧数据中对应的属性值完全相同（经过深度比较），那么新数据对象中的这个属性将直接引用旧数据对象中对应的属性。
     • 只有当某个属性的值真正发生了变化时，才会创建新的引用。
     • 最终，如果整个新对象与旧对象在结构和值上完全相同，那么整个旧对象的引用将被保留。否则，将创建一个新的顶层对象引用，但其内部未变化的子对象或数组会共享旧的引用。
   • 如果新旧数据是数组：
     • 它会比较数组的长度。如果长度不同，则肯定会创建新的数组引用。
     • 如果长度相同，它会按索引遍历数组元素，并递归地比较新旧元素。
     • 如果某个元素（包括深层嵌套的值）与旧数据中对应的元素完全相同，那么新数据数组中的这个元素将直接引用旧数据数组中对应的元素。
     • 只有当某个元素的值真正发生了变化时，才会创建新的引用。
     • 最终，如果整个新数组与旧数组在结构和值上完全相同，那么整个旧数组的引用将被保留。否则，将创建一个新的顶层数组引用，但其内部未变化的子对象或数组会共享旧的引用。

通过这种方式，TanStack Query 能够智能地“修补”数据结构，确保只有实际发生变化的子树才获得新的引用，而大量未变动的子树则继续共享旧的引用。

4. 实现细节：TanStack Query 如何实现结构化共享

TanStack Query 的结构化共享是通过其内部的数据协调 (data reconciliation) 算法实现的。这个算法在 queryClient 内部执行，是其处理查询结果的一部分。

4.1 默认行为与配置

结构化共享是 TanStack Query 的默认行为，无需额外配置。它由 QueryClient 实例自动处理。

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient({
  // 结构化共享是默认启用的，通常无需在此处显式配置
  // 除非你想完全禁用它 (不推荐，因为它会破坏很多React优化)
  // queryClientConfig: {
  //   defaultOptions: {
  //     queries: {
  //       structuralSharing: true, // 默认为 true
  //     },
  //   },
  // },
});

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      {/* Your components */}
    </QueryClientProvider>
  );
}

4.2 协调算法的简化视图

我们可以将这个协调算法想象成一个深度优先遍历，它同时检查新旧数据树。

算法步骤概览:

1. 入口点: 当 queryFn 返回新数据 newData 并且缓存中有旧数据 oldData 时，协调过程开始。
2. 类型检查:
   • 如果 newData 或 oldData 是原始值（string, number, boolean, null, undefined），或者它们的类型不同，则直接比较它们的值。如果值相等，返回 oldData；否则返回 newData。
   • 如果 newData 或 oldData 是非对象类型（如函数），则直接返回 newData。
   • 如果 newData 和 oldData 都是 Date 对象，比较它们的 getTime() 值。如果相等，返回 oldData；否则返回 newData。
   • 如果 newData 和 oldData 都是 RegExp 对象，比较它们的字符串表示。如果相等，返回 oldData；否则返回 newData。
3. 数组处理:
   • 如果 newData 和 oldData 都是数组：
     • 如果它们的长度不同，则直接返回 newData（因为数组结构已发生根本性变化）。
     • 如果长度相同，创建一个新的空数组 resultArray。
     • 遍历 newData 的每个元素 newData[i]，并与 oldData[i] 进行递归比较。
     • 将递归比较的结果 (sharedElement) 添加到 resultArray。
     • 在遍历结束后，比较 resultArray 是否与 oldData 中的所有元素引用都相同。如果是，则返回 oldData 的引用；否则返回 resultArray 的引用。
4. 对象处理:
   • 如果 newData 和 oldData 都是对象：
     • 获取 newData 的所有键 (newKeys) 和 oldData 的所有键 (oldKeys)。
     • 创建一个新的空对象 resultObject。
     • 设置一个标志 hasChanged = false。
     • 遍历 newKeys：
       • 对于每个键 key，递归比较 newData[key] 和 oldData[key]，得到 sharedValue。
       • 将 sharedValue 赋值给 resultObject[key]。
       • 如果 sharedValue 与 oldData[key] 的引用不同，则设置 hasChanged = true。
     • 遍历 oldKeys：
       • 如果 oldKeys 中存在某个键，但 newKeys 中不存在，说明该键已被删除，设置 hasChanged = true。
     • 如果 hasChanged 为 false（即所有键都相同，且所有对应的值都通过递归比较保持了引用），则返回 oldData 的引用。
     • 否则，返回 resultObject 的引用。

核心思想总结:

• 递归: 算法深度遍历数据结构。
• 引用优先: 总是尝试重用 oldData 的引用。
• 最小化变更: 只有当子树的实际内容发生变化时，才会创建新的引用。
• 逐层构建: 从底层原始值开始，向上构建共享引用。

这个算法确保了 TanStack Query 返回给 useQuery 的 data 始终是最“稳定”的引用，即在内容不变的情况下，引用也保持不变。

5. 代码示例与场景分析

现在，让我们通过具体的代码示例来观察结构化共享的效果。我们将使用 console.log 来打印对象的引用地址，以直观地判断引用是否发生了变化。

5.1 模拟 API 请求函数

为了演示，我们创建一个模拟的 API 请求函数 fetchUserData，它可以在每次调用时返回相同或不同的数据。

// utils/api.js
let currentUserData = {
  id: 1,
  name: 'Alice',
  email: '[email protected]',
  address: {
    street: '123 Main St',
    city: 'Anytown',
    zip: '12345'
  },
  roles: ['user', 'editor']
};

let callCount = 0;

export async function fetchUserData(userId) {
  callCount++;
  console.log(`--- fetchUserData API call #${callCount} for user ${userId} ---`);

  // 模拟网络延迟
  await new Promise(resolve => setTimeout(resolve, 500));

  // 场景 1: 数据完全相同
  if (callCount <= 2) {
    console.log('API returns SAME data (content-wise)');
    return { ...currentUserData }; // 返回一个新对象，但内容相同
  } 
  // 场景 2: 改变一个顶层属性
  else if (callCount === 3) {
    console.log('API returns data with TOP-LEVEL change (name)');
    currentUserData = { ...currentUserData, name: 'Alicia' };
    return { ...currentUserData };
  }
  // 场景 3: 改变一个嵌套对象属性
  else if (callCount === 4) {
    console.log('API returns data with NESTED object change (city)');
    currentUserData = {
      ...currentUserData,
      address: {
        ...currentUserData.address,
        city: 'New City'
      }
    };
    return { ...currentUserData };
  }
  // 场景 4: 改变一个数组元素
  else if (callCount === 5) {
    console.log('API returns data with ARRAY element change (roles)');
    currentUserData = {
      ...currentUserData,
      roles: ['admin', 'user'] // 改变了顺序和内容
    };
    return { ...currentUserData };
  }
  // 场景 5: 再次返回相同数据
  else {
    console.log('API returns SAME data again');
    return { ...currentUserData };
  }
}

5.2 React 组件中的使用

我们将创建一个 UserDisplay 组件来消费数据，并使用 React.memo 来观察渲染行为。

// components/UserDisplay.jsx
import React from 'react';

// 使用 React.memo 包装，只有当 props 引用改变时才重新渲染
const UserDisplay = React.memo(({ user }) => {
  console.log('  UserDisplay RENDERED!');
  console.log('    User object reference:', user);
  console.log('    User.address reference:', user?.address);
  console.log('    User.roles reference:', user?.roles);

  if (!user) {
    return <div>Loading user...</div>;
  }

  return (
    <div style={{ border: '1px solid #ccc', padding: '10px', margin: '10px 0' }}>
      <h4>Current User Data</h4>
      <p>ID: {user.id}</p>
      <p>Name: {user.name}</p>
      <p>Email: {user.email}</p>
      {user.address && (
        <>
          <h5>Address</h5>
          <p>Street: {user.address.street}</p>
          <p>City: {user.address.city}</p>
          <p>Zip: {user.address.zip}</p>
        </>
      )}
      {user.roles && (
        <>
          <h5>Roles</h5>
          <ul>
            {user.roles.map((role, index) => (
              <li key={index}>{role}</li>
            ))}
          </ul>
        </>
      )}
    </div>
  );
});

export default UserDisplay;

5.3 主应用组件

// App.jsx
import React, { useState, useEffect, useCallback } from 'react';
import { useQuery, QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { fetchUserData } from './utils/api';
import UserDisplay from './components/UserDisplay';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // 为了演示，我们将 staleTime 设置为 1 秒，这样可以快速看到 refetch
      // 真实应用中可能设置为 5 * 60 * 1000 (5分钟) 或更高
      staleTime: 1000, 
    },
  },
});

function AppContent() {
  const [userId, setUserId] = useState(1);
  const [intervalRefetchEnabled, setIntervalRefetchEnabled] = useState(true);

  // 使用 useQuery 获取用户数据
  const { data, isLoading, isFetching, error, refetch } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUserData(userId),
    // 禁用 retry 以便清晰看到错误
    retry: false, 
  });

  // 模拟周期性 refetch，观察结构化共享效果
  useEffect(() => {
    if (!intervalRefetchEnabled) return;

    const intervalId = setInterval(() => {
      console.log('n--- Automatic refetch triggered ---');
      refetch();
    }, 3000); // 每3秒触发一次 refetch

    return () => clearInterval(intervalId);
  }, [refetch, intervalRefetchEnabled]);

  console.log('AppContent RENDERED!');
  console.log('  useQuery data reference (top-level):', data);

  if (isLoading) return <div>Loading initial user data...</div>;
  if (error) return <div>An error occurred: {error.message}</div>;

  return (
    <div>
      <h1>TanStack Query Structural Sharing Demo</h1>
      <p>
        Current User ID: {userId} | Status: {isFetching ? 'Fetching...' : 'Idle'}
      </p>
      <button onClick={() => setUserId(userId === 1 ? 2 : 1)}>
        Switch User ID (will trigger new query)
      </button>
      <button onClick={() => refetch()} disabled={isFetching}>
        Manually Refetch Current User
      </button>
      <button onClick={() => setIntervalRefetchEnabled(prev => !prev)}>
        {intervalRefetchEnabled ? 'Disable Auto Refetch' : 'Enable Auto Refetch'}
      </button>

      {/* 将 useQuery 返回的数据传递给子组件 */}
      <UserDisplay user={data} />
    </div>
  );
}

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <AppContent />
    </QueryClientProvider>
  );
}

export default App;

运行与观察结果 (控制台输出)

让我们分步分析控制台输出，理解结构化共享的威力。

1. 初始加载 (Call #1)

• fetchUserData API call #1 for user 1
• API returns SAME data (content-wise)
• AppContent RENDERED!
• useQuery data reference (top-level): {id: 1, name: 'Alice', ...} (假设地址 0x100)
• UserDisplay RENDERED!
• User object reference: {id: 1, name: 'Alice', ...} (地址 0x100)
• User.address reference: {street: '123 Main St', city: 'Anytown', ...} (假设地址 0x101)
• User.roles reference: ['user', 'editor'] (假设地址 0x102)

2. 第一次自动 Refetch (Call #2)，API 返回相同内容

• --- Automatic refetch triggered ---
• --- fetchUserData API call #2 for user 1 ---
• API returns SAME data (content-wise)
• AppContent RENDERED!
• useQuery data reference (top-level): {id: 1, name: 'Alice', ...} (地址 0x100 – 引用未变!)
• UserDisplay 未渲染! (因为 user prop 的引用 0x100 没有改变，React.memo 起作用了)

解释: 尽管 fetchUserData 返回了一个新的对象 { ...currentUserData }，但 TanStack Query 的结构化共享机制发现其内容与缓存中的旧数据完全一致。因此，它决定继续返回旧数据的引用 (0x100)。这使得 AppContent 重新渲染时，UserDisplay 的 user prop 仍然是 0x100，React.memo 成功阻止了 UserDisplay 的不必要渲染。这是结构化共享最直接的体现。

3. 第二次自动 Refetch (Call #3)，API 改变顶层 name 属性

• --- Automatic refetch triggered ---
• --- fetchUserData API call #3 for user 1 ---
• API returns data with TOP-LEVEL change (name)
• AppContent RENDERED!
• useQuery data reference (top-level): {id: 1, name: 'Alicia', ...} (假设地址 0x200 – 引用改变!)
• UserDisplay RENDERED!
• User object reference: {id: 1, name: 'Alicia', ...} (地址 0x200)
• User.address reference: {street: '123 Main St', city: 'Anytown', ...} (地址 0x101 – 引用未变!)
• User.roles reference: ['user', 'editor'] (地址 0x102 – 引用未变!)

解释: 此时 fetchUserData 返回的数据 name 属性从 ‘Alice’ 变为 ‘Alicia’。由于顶层对象发生了变化，TanStack Query 必须返回一个新的顶层数据引用 (0x200)。因此 AppContent 和 UserDisplay 都重新渲染了。

关键点: 尽管顶层对象引用改变了，但注意 User.address 和 User.roles 的引用 (0x101, 0x102) 并没有改变！这是因为结构化共享递归地比较了数据，发现 address 对象和 roles 数组的内容没有变化，因此它们仍然共享旧的引用。如果 UserDisplay 内部有组件只依赖于 user.address，并且它也使用了 React.memo，那么它就不会重新渲染。

4. 第三次自动 Refetch (Call #4)，API 改变嵌套 address.city 属性

• --- Automatic refetch triggered ---
• --- fetchUserData API call #4 for user 1 ---
• API returns data with NESTED object change (city)
• AppContent RENDERED!
• useQuery data reference (top-level): {id: 1, name: 'Alicia', ...} (假设地址 0x300 – 引用改变!)
• UserDisplay RENDERED!
• User object reference: {id: 1, name: 'Alicia', ...} (地址 0x300)
• User.address reference: {street: '123 Main St', city: 'New City', ...} (假设地址 0x301 – 引用改变!)
• User.roles reference: ['user', 'editor'] (地址 0x102 – 引用未变!)

解释: address.city 发生了变化。为了反映这个变化，TanStack Query 必须创建新的 address 对象引用 (0x301)。由于 address 对象是顶层 data 的属性，所以顶层 data 也必须获得一个新的引用 (0x300)。但是，roles 数组的内容和引用 (0x102) 依然保持不变。

5. 第四次自动 Refetch (Call #5)，API 改变 roles 数组

• --- Automatic refetch triggered ---
• --- fetchUserData API call #5 for user 1 ---
• API returns data with ARRAY element change (roles)
• AppContent RENDERED!
• useQuery data reference (top-level): {id: 1, name: 'Alicia', ...} (假设地址 0x400 – 引用改变!)
• UserDisplay RENDERED!
• User object reference: {id: 1, name: 'Alicia', ...} (地址 0x400)
• User.address reference: {street: '123 Main St', city: 'New City', ...} (地址 0x301 – 引用未变!)
• User.roles reference: ['admin', 'user'] (假设地址 0x402 – 引用改变!)

解释: roles 数组的内容发生了变化。为了反映这个变化，TanStack Query 必须创建新的 roles 数组引用 (0x402)。由于 roles 数组是顶层 data 的属性，所以顶层 data 也必须获得一个新的引用 (0x400)。但是，address 对象的内容和引用 (0x301) 依然保持不变。

5.4 总结示例：结构化共享的优势

通过这些示例，我们清楚地看到：

• 当 API 返回的数据在内容上与缓存数据完全一致时，TanStack Query 会保持顶层 data 的引用不变，从而避免 React.memo 组件的不必要渲染。
• 当数据发生部分变化时，TanStack Query 会智能地只更新发生变化部分的引用，而未变化部分的深层嵌套对象或数组仍然共享旧的引用。这允许更细粒度的 React 优化。

这种行为极大地简化了 React 应用的性能优化，开发者无需手动进行复杂的深度比较或 Immutable.js 转换，就能享受到引用稳定带来的好处。

6. 结构化共享的收益与考量

结构化共享无疑是 TanStack Query 的一个强大特性，但如同所有优化，它也有其收益与潜在的考量。

6.1 核心收益

1. 显著减少不必要的 React 渲染： 这是最直接和最重要的好处。当数据内容未变时，组件不会重新渲染，从而节省 CPU 周期，提高用户界面响应速度和流畅性。
2. 增强 React.memo 和 useMemo/useCallback 的有效性： 结构化共享使得这些 React 优化机制能够更可靠地工作，因为它们依赖的 data 引用变得稳定。开发者可以更放心地使用它们，而无需担心频繁的引用变化导致缓存失效。
3. 简化开发者的心智负担： 开发者无需手动编写复杂的数据比较逻辑，也不用担心 API 每次返回新对象引用的问题。TanStack Query 自动处理了这一复杂性。
4. 提高应用性能： 减少渲染次数和计算可以显著提升大型或数据密集型应用的整体性能。
5. 与 Immutable Data Patterns 协同： 虽然 TanStack Query 内部实现了数据协调，但它鼓励了一种“结果数据是不可变”的思维模式，这与 React 生态系统中常见的函数式和不可变数据模式非常契合。

6.2 潜在考量与权衡

1. 深层比较的计算成本： 结构化共享的核心是深度比较。对于非常庞大且嵌套极深的数据结构，每次重新获取后的深度比较可能会引入一定的 CPU 开销。然而，对于绝大多数典型的 API 响应，这个开销通常可以忽略不计，远低于因不必要渲染而带来的性能损失。TanStack Query 的内部实现是高度优化的。
2. 内存占用： 为了实现引用共享，TanStack Query 需要在内存中同时保留旧数据和新数据（在比较过程中）。虽然这通常不是问题，但在处理极其巨大的数据集时，需要考虑。
3. 不适用于所有数据类型： 结构化共享主要针对普通 JavaScript 对象和数组。对于其他复杂类型（如 Map, Set, Blob, File），它可能不会进行深度比较，或者行为可能不同。但通常 API 返回的数据都是 JSON 可序列化的对象和数组。
4. 开发者对数据变动的直觉： 如果开发者不理解结构化共享，可能会在调试时感到困惑，为什么 console.log(data) 看起来相同但引用却不变，或者为什么某个深层属性变了但顶层引用没变。理解其原理有助于更好地利用和调试。

总结表格：收益与考量

特性维度	收益	考量
性能	显著减少 React 不必要渲染；提高组件 (React.memo) 和 Hook (useMemo) 优化效率。	深层比较可能产生计算开销（通常可忽略）；内存占用略高（同时保留旧新数据）。
开发体验	简化数据管理和优化逻辑；降低心智负担；无需手动实现复杂的引用保持逻辑。	如果不理解原理，可能对引用保持行为感到困惑；不适用于所有特殊数据类型。
稳定性	提供稳定的数据引用，减少因引用变化导致的副作用和 bug。
兼容性	与 React 现有优化机制（如 React.memo）无缝集成。

7. 何时结构化共享可能不足，以及如何配合其他工具

尽管结构化共享功能强大，但在某些特定场景下，你可能需要额外的策略或工具来处理数据。

7.1 select 选项：在结构化共享之后进行数据转换

TanStack Query 的 select 选项允许你在 queryFn 返回数据后，但在数据进入缓存并被 useQuery 返回之前，对数据进行转换。

import { useQuery } from '@tanstack/react-query';
import { fetchUserData } from './utils/api';

function MyComponent({ userId }) {
  const { data: userEmail, isLoading } = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUserData(userId),
    // 使用 select 选项，只提取 email 属性
    select: (data) => data?.email,
  });

  console.log('User email reference:', userEmail); // 每次 select 都会返回新的引用
                                                // 但其依赖的原始 'data' 仍然享受结构化共享

  if (isLoading) return <div>Loading email...</div>;
  return <div>User Email: {userEmail}</div>;
}

重要提示： select 函数每次运行时，都会返回一个新的引用（除非你返回一个原始值或缓存了它）。这意味着即使原始 data 经过结构化共享后引用未变，select 返回的结果的引用也可能会变。

然而，这并非结构化共享的缺陷。select 的目的是转换数据。结构化共享仍然作用于 queryFn 返回的原始数据。如果 select 函数的输出依赖于 data 的某个子集，而这个子集在原始 data 中引用稳定，那么 select 返回的引用也可能稳定。但更常见的是，select 会从原始数据中提取或计算出新的值，这必然会导致新的引用。

最佳实践： 尽可能在 select 中返回原始值或最小化处理后的对象，并且只在你真正需要转换或提取数据时使用 select。

7.2 手动数据规范化 (Normalization)：更细粒度的控制

对于极其复杂、相互关联且经常更新的数据集（例如社交网络中的用户、帖子、评论等），你可能需要更高级的数据规范化策略。像 Redux Toolkit 提供的 createEntityAdapter 或专门的规范化库 (如 normalizr) 可以帮助你将数据扁平化，存储为实体 (entities) 和它们的 ID 列表 (ids)。

在这种情况下：

• TanStack Query 仍然可以用来获取原始的、非规范化的 API 响应。
• 你可以在 queryFn 之后，但在数据进入你的全局状态管理（如 Redux）之前，进行手动规范化。
• 结构化共享仍然作用于 TanStack Query 缓存中的原始 API 响应。
• 你的全局状态管理层负责维护规范化后的数据的引用稳定性。

例如，你可以这样结合：

// queryFn 返回原始数据
const fetchPosts = async () => { /* ... */ return [{id: 1, author: {id: 101, name: 'Alice'}, ...}] };

// select 中进行规范化 (或者在 Redux reducer 中进行)
const normalizedData = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  select: (posts) => {
    // 使用 normalizr 或手动逻辑将 posts 扁平化为 entities: { posts: {...}, users: {...} }
    const normalized = normalize(posts, [postSchema]); // 假设 postSchema
    return normalized.entities;
  },
});

在这种情况下，useQuery 返回的 normalizedData 的引用稳定性将取决于你的规范化逻辑。结构化共享依然在幕后确保 fetchPosts 返回的原始数据在缓存中尽可能稳定。

7.3 大型、动态变化的数据：权衡性能

如果你的 API 返回的数据结构非常庞大（例如，包含数万个元素的数组，每个元素又是复杂对象），并且这些数据在每次 refetch 时都可能发生大规模的变化，那么 TanStack Query 的深度比较开销可能会变得明显。

在这种极端情况下：

• 考虑禁用结构化共享： 你可以通过在 queryClient 的 defaultOptions.queries 中设置 structuralSharing: false 来禁用它。这将导致 useQuery 每次 refetch 后都会返回新的数据引用，即使内容相同。但你将承担因此带来的不必要渲染。
• 优化 API 响应： 尽可能让 API 只返回实际发生变化的数据，或者使用分页、增量更新等策略。
• 客户端自定义比较： 如果需要，你可以实现自定义的比较逻辑，但通常这比使用 TanStack Query 的默认行为更复杂。

通常，对于 Web 应用，API 响应的数据量不会达到需要禁用结构化共享的程度。它的优化效益远大于其潜在的计算成本。

8. 最佳实践和建议

为了充分利用 TanStack Query 的结构化共享，并构建高性能的 React 应用，请遵循以下最佳实践：

1. 将数据视为不可变 (Immutable)： 从 useQuery 返回的 data 应该被视为不可变的。不要直接修改 data 对象或其嵌套属性。如果你需要修改数据，请先创建副本：

   // ❌ BAD: 直接修改 useQuery 返回的数据
   // data.name = 'Bob'; 
   
   // ✅ GOOD: 创建副本进行修改
   const updatedData = { ...data, name: 'Bob' };

   直接修改会破坏 TanStack Query 对数据引用的管理，导致不可预测的行为和调试困难。

2. 善用 React.memo 和 useMemo/useCallback： 结构化共享使得这些 React 优化工具能够真正发挥作用。将它们应用于你的子组件和昂贵计算，以最大化性能收益。

   // ChildComponent.jsx
   const ChildComponent = React.memo(({ user }) => { /* ... */ });
   
   // ParentComponent.jsx
   const memoizedValue = useMemo(() => calculateSomething(data.items), [data.items]);

3. 理解你的数据结构： 了解你的 API 如何返回数据，以及哪些部分可能会频繁变化，哪些部分相对稳定。这有助于你预测结构化共享的行为。

4. 避免手动深度克隆或比较： 除非有非常特殊的需求，否则不要在从 useQuery 获取的数据上执行 JSON.parse(JSON.stringify(data)) 或 lodash 的 cloneDeep。TanStack Query 已经为你处理了数据引用的稳定性。

5. 使用 console.log 验证引用： 在开发过程中，利用 console.log 打印对象引用（例如 console.log(data, data.address)）是一个非常有用的调试技巧，可以帮助你直观地理解结构化共享何时生效，何时引用会发生变化。

6. 合理设置 staleTime 和 cacheTime： 这些参数影响数据何时被视为过期以及何时从缓存中移除。它们与结构化共享协同工作，共同管理数据的生命周期。

总结

TanStack Query 的结构化共享是一个强大而默认启用的特性，它通过智能的深度比较和引用重用机制，确保在 API 返回相同内容的数据时，React 组件的引用保持不变。这一机制显著减少了不必要的渲染，提升了 React.memo 和 useMemo/useCallback 等优化手段的效率，极大地简化了 React 应用中的数据管理和性能优化。理解并利用好结构化共享，是构建高性能、可维护的现代 React 应用的关键。