Vue3 组合式架构：从响应式原理到全栈应用的状态治理

一、当响应式变成"响应式陷阱"：Vue3 全栈应用的状态困局

Vue3 的组合式 API（Composition API）极大提升了代码组织能力，但在全栈应用中，状态管理的复杂度远超单页应用。服务端渲染（SSR）时的状态水合（Hydration）、跨组件的依赖注入、Pinia Store 的模块拆分——每一个环节都可能成为性能瓶颈或内存泄漏的源头。

最典型的场景：一个电商应用的商品详情页，服务端渲染时需要预取商品数据、用户信息、推荐列表，这些数据通过 useState 或 Pinia 注入到组件树中。但客户端水合时，如果状态序列化/反序列化不一致，轻则数据闪烁，重则水合不匹配导致整页重新渲染。更隐蔽的问题是，组合式函数（Composable）中未清理的副作用（如 watch、onMounted 中的定时器）在 SSR 环境下会跨请求泄漏。

本文将从 Vue3 响应式系统的底层机制出发，系统梳理全栈应用中的状态治理方案。

二、Proxy 与依赖追踪：Vue3 响应式的底层机制

Vue3 的响应式系统基于 ES6 Proxy 实现，核心流程分为三个阶段：依赖收集、触发更新、调度执行。

sequenceDiagram
    participant C as 组件渲染函数
    participant E as effect 副作用
    participant T as target (Proxy)
    participant D as depsMap 依赖映射

    C->>E: 执行渲染函数
    E->>T: 读取 reactive state
    T->>D: track() 收集当前 effect
    Note over T,D: 依赖收集阶段

    T->>D: 属性被修改 trigger()
    D->>E: 通知所有依赖的 effect
    E->>C: 重新执行渲染函数
    Note over D,C: 触发更新阶段

关键实现细节：

依赖收集的时机：当 effect（如组件渲染函数）执行时，通过全局的 activeEffect 标记当前正在运行的副作用。Proxy 的 get 拦截器检测到 activeEffect 存在时，将当前属性与 activeEffect 建立映射关系。

依赖的数据结构：每个响应式对象对应一个 depsMap（Map 结构），key 是属性名，value 是 Dep（Set 结构，存储所有依赖该属性的 effect）。这种两层 Map 结构使得精确触发成为可能——修改 obj.name 只触发依赖 name 的 effect，不影响 obj.age 的订阅者。

调度器的缓冲机制：Vue3 默认使用队列调度（queueJob），同一事件循环内的多次修改只会触发一次渲染。这避免了 a++; b++; 导致的两次渲染，但也在某些场景下需要用 nextTick 确保 DOM 更新完成。

SSR 中的特殊处理：服务端渲染时，effect 的调度器被替换为同步执行（无需排队），因为服务端没有 DOM 更新的需求。但 onMounted、onUnmounted 等生命周期钩子在 SSR 中不会执行，如果 Composable 在这些钩子中注册副作用，SSR 环境下会被跳过——这正是跨请求状态泄漏的根源。

三、全栈状态治理：Composable 设计与 SSR 安全

// useAsyncData.ts —— SSR 安全的异步数据获取 Composable
import { ref, onServerPrefetch, onUnmounted } from "vue";
import type { Ref } from "vue";

interface AsyncDataOptions<T> {
  // 服务端预取的 key，用于状态水合
  key: string;
  // 初始值，避免 undefined 导致的类型问题
  initial?: T;
  // 客户端是否重新获取（默认 false，复用服务端数据）
  server?: boolean;
  // 请求超时时间（毫秒）
  timeout?: number;
}

interface AsyncDataResult<T> {
  data: Ref<T | undefined>;
  error: Ref<Error | null>;
  pending: Ref<boolean>;
  refresh: () => Promise<void>;
}

export function useAsyncData<T>(
  fetcher: () => Promise<T>,
  options: AsyncDataOptions<T>
): AsyncDataResult<T> {
  const data = ref<T | undefined>(options.initial) as Ref<T | undefined>;
  const error = ref<Error | null>(null);
  const pending = ref(false);

  // 超时控制——防止 SSR 时 fetcher 卡住导致请求阻塞
  const timeout = options.timeout ?? 5000;

  async function execute(): Promise<void> {
    pending.value = true;
    error.value = null;

    try {
      const result = await Promise.race([
        fetcher(),
        new Promise<never>((_, reject) =>
          setTimeout(() => reject(new Error(`请求超时: ${options.key}`)), timeout)
        ),
      ]);
      data.value = result as T;
    } catch (err) {
      error.value = err as Error;
    } finally {
      pending.value = false;
    }
  }

  // SSR 环境：在 serverPrefetch 中执行，数据自动序列化到页面 HTML
  onServerPrefetch(async () => {
    await execute();
  });

  // 客户端环境：检查是否有服务端水合的数据
  if (import.meta.client) {
    const nuxtApp = useNuxtApp();
    const hydrated = nuxtApp.payload.data?.[options.key];

    if (hydrated !== undefined) {
      // 水合成功，直接使用服务端数据
      data.value = hydrated;
    } else if (options.server !== false) {
      // 无水合数据且允许客户端获取，执行 fetch
      execute();
    }
  }

  // 组件卸载时清理——防止内存泄漏
  onUnmounted(() => {
    data.value = undefined;
    error.value = null;
  });

  return {
    data,
    error,
    pending,
    refresh: execute,
  };
}

// useEventSource.ts —— 带自动清理的 SSE 连接 Composable
import { ref, onMounted, onUnmounted } from "vue";

interface EventSourceOptions {
  url: string;
  // 自动重连间隔（毫秒），0 表示不重连
  reconnectInterval?: number;
  // 最大重连次数
  maxReconnects?: number;
}

export function useEventSource(options: EventSourceOptions) {
  const data = ref<string | null>(null);
  const isConnected = ref(false);
  const error = ref<Event | null>(null);

  let eventSource: EventSource | null = null;
  let reconnectCount = 0;
  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;

  const maxReconnects = options.maxReconnects ?? 3;
  const reconnectInterval = options.reconnectInterval ?? 3000;

  function connect(): void {
    // 清理旧连接
    disconnect();

    eventSource = new EventSource(options.url);

    eventSource.onopen = () => {
      isConnected.value = true;
      reconnectCount = 0; // 连接成功，重置重连计数
    };

    eventSource.onmessage = (event) => {
      data.value = event.data;
    };

    eventSource.onerror = (event) => {
      error.value = event;
      isConnected.value = false;

      // 自动重连逻辑
      if (reconnectCount < maxReconnects) {
        reconnectCount++;
        reconnectTimer = setTimeout(connect, reconnectInterval);
      } else {
        // 重连耗尽，关闭连接
        disconnect();
      }
    };
  }

  function disconnect(): void {
    if (eventSource) {
      eventSource.close();
      eventSource = null;
    }
    if (reconnectTimer) {
      clearTimeout(reconnectTimer);
      reconnectTimer = null;
    }
    isConnected.value = false;
  }

  // 仅在客户端建立连接——SSR 环境无 EventSource API
  onMounted(() => {
    connect();
  });

  // 组件卸载时必须清理，否则连接泄漏
  onUnmounted(() => {
    disconnect();
  });

  return { data, isConnected, error, reconnect: connect };
}

// Pinia Store 模块化拆分示例
import { defineStore } from "pinia";

// 商品详情 Store——独立管理，避免与用户 Store 耦合
export const useProductStore = defineStore("product", () => {
  const product = ref<Product | null>(null);
  const recommendations = ref<Product[]>([]);
  const loading = ref(false);

  async function fetchProduct(id: string): Promise<void> {
    loading.value = true;
    try {
      const [productRes, recRes] = await Promise.all([
        api.getProduct(id),
        api.getRecommendations(id),
      ]);
      product.value = productRes;
      recommendations.value = recRes;
    } catch (err) {
      // 错误向上抛出，由 Composable 层统一处理
      throw err;
    } finally {
      loading.value = false;
    }
  }

  // $reset 支持——组合式 API 需手动实现
  function $reset(): void {
    product.value = null;
    recommendations.value = [];
    loading.value = false;
  }

  return { product, recommendations, loading, fetchProduct, $reset };
});

四、响应式的代价：全栈状态治理的架构权衡

Proxy 的性能开销：Vue3 的 Proxy 响应式在深层嵌套对象上存在惰性代理的延迟。访问 state.a.b.c 时，每一层都会触发 get 拦截器并创建代理。对于频繁读写的热点数据（如动画帧率计数器），建议使用 shallowRef 或 markRaw 跳过深层响应式。

SSR 状态水合的序列化限制：useState 和 Pinia 的 SSR 状态通过 JSON.stringify 序列化，不支持 Map、Set、Date、RegExp 等类型。如果 Store 中包含这些类型，水合时会丢失。解决方案是在服务端渲染前将特殊类型转换为普通对象，客户端水合后再还原。

Composable 的隐式依赖：组合式函数的调用顺序和位置决定了其生命周期绑定关系。在 setup 之外调用 Composable 会导致生命周期钩子失效。团队协作中，建议通过 ESLint 规则强制约束 Composable 只能在 setup 中调用。

适用边界：此方案适用于 Vue3 + Nuxt3 的全栈应用，页面级状态通过 useAsyncData 管理，全局状态通过 Pinia Store 管理。对于纯客户端 SPA，可以简化 SSR 相关逻辑，但副作用清理（onUnmounted）仍然不可省略。

五、总结

Vue3 全栈应用的状态治理，核心在于理解响应式系统的底层机制并据此设计约束。Proxy 的依赖追踪是性能优化的基础，SSR 的水合一致性是正确性的保障，Composable 的副作用清理是内存安全的底线。落地时建议建立团队级的 Composable 设计规范：每个 Composable 必须声明其副作用、必须实现 onUnmounted 清理、SSR 场景必须考虑水合兼容性。少即是多，约束即自由。