Vue3 组合式架构拆解：从 Proxy 响应式到 Composable 的设计纪律

一、Options API 的隐式耦合与逻辑分散问题

Vue2 的 Options API 将组件逻辑按选项类型（data、methods、computed、watch）组织，这在简单组件中清晰直观。但当组件复杂度上升——一个用户详情页同时包含权限校验、数据加载、表单校验、操作日志四个关注点——每个关注点的逻辑被分散到 data、methods、computed、watch 四个选项中，形成"横切关注点"的交叉分散。

更严重的问题是隐式耦合：methods 中的函数可以访问 data 中的所有属性、computed 中的所有计算属性，没有任何访问边界。一个 fetchUserData 方法可能同时依赖 userId、token、filters 三个 data 属性，但这种依赖关系在代码中不可见——只有运行时才能追踪。

组合式 API（Composition API）的核心价值不是"更灵活的写法"，而是"逻辑内聚与显式依赖"。通过 Composable 函数，将同一关注点的状态、计算、副作用封装在一个函数中，依赖关系通过参数和返回值显式声明。

二、Proxy 响应式系统的底层机制

Vue3 使用 ES6 Proxy 替代 Vue2 的 Object.defineProperty，实现了真正意义上的深层响应式。理解 Proxy 的工作机制，是写出高性能组合式代码的前提。

flowchart TB
    Target[原始对象 target] --> Proxy[Proxy 代理]
    Proxy -->|读取属性| GetTrap[get 拦截器]
    Proxy -->|写入属性| SetTrap[set 拦截器]
    Proxy -->|删除属性| DeleteTrap[deleteProperty 拦截器]

    GetTrap --> Track[track: 收集依赖]
    Track --> Effect[当前活跃的 ReactiveEffect]
    Effect --> DepMap[targetMap → depsMap → dep Set]

    SetTrap --> Trigger[trigger: 触发更新]
    Trigger --> DepSet[遍历 dep Set 中的所有 Effect]
    DepSet --> Scheduler[scheduler 调度执行]
    Scheduler -->|同步| Run[effect.fn 执行]
    Scheduler -->|异步| Queue[加入微任务队列]

    style Track fill:#9ff,stroke:#333
    style Trigger fill:#f99,stroke:#333

关键机制解析：

• track（依赖收集）：当 effect.fn 执行过程中读取响应式属性时，get 拦截器被触发，将当前 Effect 记录到该属性的 dep Set 中。这就是"谁读了我，我就记住谁"。
• trigger（触发更新）：当响应式属性被写入时，set 拦截器被触发，遍历该属性的 dep Set，通知所有依赖此属性的 Effect 重新执行。
• 调度策略：Vue3 默认使用异步调度——同一事件循环内的多次状态变更，只触发一次组件更新。这避免了 Vue2 中常见的"中间状态渲染"问题。

Proxy 相比 Object.defineProperty 的根本优势：Proxy 可以拦截对象的所有操作（包括属性新增、删除、has、ownKeys），无需像 Vue2 那样递归遍历对象预先定义 getter/setter。这也意味着 Vue3 的响应式是"惰性"的——只有被访问到的嵌套对象才会被代理，未访问的深层对象保持原样。

三、Composable 设计纪律与生产级实践

3.1 Composable 的命名约定与接口设计

import { ref, computed, watch, onUnmounted, readonly } from 'vue';

// Composable 命名规范：use 前缀 + 名词，返回值用对象解构
// 返回值分为两类：状态（ref/computed）和方法（函数）
// 状态默认只读，避免外部直接修改导致数据流不可追踪
export function useUserPermission(userId: Ref<string>) {
  // 内部状态——可变
  const permissions = ref<string[]>([]);
  const loading = ref(false);
  const error = ref<Error | null>(null);

  // 计算属性——派生状态
  const isAdmin = computed(() => permissions.value.includes('admin'));
  const canEdit = computed(() =>
    permissions.value.some((p) => ['admin', 'editor'].includes(p)),
  );

  // 方法——副作用与状态变更
  async function fetchPermissions() {
    loading.value = true;
    error.value = null;
    try {
      const res = await api.getUserPermissions(userId.value);
      permissions.value = res.data;
    } catch (e) {
      error.value = e as Error;
      // 不吞掉错误，让调用方决定如何处理
    } finally {
      loading.value = false;
    }
  }

  // 副作用自动清理——watch 返回的 stop 函数在组件卸载时自动调用
  const stopWatch = watch(userId, (newId) => {
    if (newId) {
      fetchPermissions();
    }
  });

  onUnmounted(() => {
    stopWatch();
  });

  // 返回值：状态只读，方法可调用
  // 这是 Composable 的"契约"——外部只能通过方法改变内部状态
  return {
    permissions: readonly(permissions),
    loading: readonly(loading),
    error: readonly(error),
    isAdmin,
    canEdit,
    fetchPermissions,
  };
}

3.2 Composable 的组合与依赖注入

// 组合模式：一个 Composable 可以依赖另一个 Composable
// 这是替代 Mixin 的核心机制——依赖关系显式声明
export function useProtectedResource(resourceId: Ref<string>) {
  // 依赖 useUserPermission，显式传入 userId
  const userId = ref(''); // 从全局状态或路由参数获取
  const { canEdit, isAdmin } = useUserPermission(userId);

  const resource = ref<Resource | null>(null);
  const saving = ref(false);

  async function saveResource(data: Partial<Resource>) {
    // 权限校验在 Composable 内部完成，而非组件中
    // 这保证了权限逻辑不会被绕过
    if (!canEdit.value) {
      throw new Error('无编辑权限');
    }

    saving.value = true;
    try {
      const res = await api.updateResource(resourceId.value, data);
      resource.value = res.data;
    } finally {
      saving.value = false;
    }
  }

  return {
    resource: readonly(resource),
    saving: readonly(saving),
    canEdit,
    isAdmin,
    saveResource,
  };
}

3.3 响应式性能陷阱：避免不必要的深层代理

import { ref, shallowRef, shallowReactive, markRaw, triggerRef } from 'vue';

// 陷阱 1：大对象的全量代理
// 反模式：将整个 API 响应（可能包含数百个字段）用 ref 包裹
// Vue3 会递归代理所有嵌套属性，开销与对象深度成正比
const badData = ref(largeApiResponse); // 可能包含 100+ 嵌套属性

// 正解：对于只读的大对象，使用 shallowRef + markRaw
// shallowRef 只代理 .value 本身，不递归代理内部属性
// markRaw 告诉 Vue 跳过此对象的响应式转换
const goodData = shallowRef(markRaw(largeApiResponse));

// 当需要更新 shallowRef 时，必须替换整个 .value 触发更新
// triggerRef 强制触发依赖更新
function updateData(newData: ApiResponse) {
  goodData.value = markRaw(newData);
  triggerRef(goodData); // 显式通知依赖
}

// 陷阱 2：频繁更新的列表数据
// 反模式：用 reactive 包裹列表，每次增删都触发全量代理
const badList = reactive<Item[]>([]);

// 正解：shallowReactive 只代理数组本身（length、索引赋值）
// 内部元素保持原始对象，不递归代理
const goodList = shallowReactive<Item[]>([]);

四、组合式 API 的设计边界与反模式

Composable 不是万能的。以下场景不适合用 Composable 抽象：

• 一次性逻辑：只在某个组件中使用一次的逻辑，强行抽成 Composable 反而增加了间接层。Composable 的价值在于复用，不复用的逻辑留在组件内即可。
• 强 UI 耦合的逻辑：如果逻辑与 DOM 结构深度绑定（如拖拽排序的 DOM 操作），抽成 Composable 会导致 Composable 需要接收大量 DOM ref，接口变得臃肿。这类逻辑更适合用自定义指令封装。

另一个常见反模式是"Composable 套 Composable"的深层嵌套。当 A Composable 依赖 B Composable，B 又依赖 C，调用链超过 3 层时，调试和测试的复杂度会急剧上升。建议将 Composable 的依赖深度控制在 2 层以内，超过 2 层时考虑合并或使用 Provide/Inject 解耦。

响应式性能方面，reactive 和 ref 的选择也有讲究：reactive 适用于结构稳定的对象（字段不增删），ref 适用于需要整体替换的值。将一个频繁整体替换的对象用 reactive 包裹，每次替换都需要 Object.assign 逐字段赋值，既不直观也不高效。

五、总结

Vue3 组合式架构的核心纪律是"逻辑内聚、依赖显式、状态只读"。Composable 函数将同一关注点的状态、计算和副作用封装在一起，通过参数声明依赖、通过返回值暴露接口，通过 readonly 保证外部不可直接修改内部状态。响应式性能优化的关键在于"按需代理"：对只读大对象使用 shallowRef + markRaw，对频繁更新的列表使用 shallowReactive，避免 Vue3 的递归代理机制在不必要的场景下消耗性能。Composable 的抽象粒度应以"复用"为标准——不复用的逻辑不抽象，强 UI 耦合的逻辑用指令封装，依赖深度不超过 2 层。