1. 核心概念与用法

Vue 3 的 Composition API 引入了一套全新的、基于函数的 API，旨在解决在构建大型复杂应用时，Options API 所面临的代码组织困难和逻辑复用性差的痛点。它并非要完全取代 Options API，而是提供了一种更灵活、更强大的替代方案，让开发者能够根据逻辑关注点来组织代码，而不是被限制在 data、methods、computed 等固定的选项中。这套 API 的核心思想是将组件的逻辑拆分成更小、更独立的函数，这些函数可以根据需要自由组合，从而极大地提升了代码的可读性、可维护性和复用性。Composition API 主要包含响应式 API（如 ref 和 reactive）、生命周期钩子（如 onMounted）以及依赖注入（如 provide 和 inject）等，它们共同构成了一个功能强大的工具集，使开发者能够以更函数式、更模块化的方式来构建 Vue 组件。

1.1 `setup()` 函数：Composition API 的入口

setup() 函数是 Composition API 的核心和入口点。它在组件实例被创建之前执行，是组织组件逻辑的主要场所。与 Options API 中逻辑分散在各个选项（data, methods, computed 等）不同，setup() 允许我们将相关的状态、方法、计算属性等逻辑集中在一起，按照功能模块进行组织，从而解决了复杂组件中逻辑分散、难以追踪的问题。这个函数接收两个参数：props 和 context。props 是一个响应式对象，包含了父组件传递过来的所有属性，当父组件的 props 发生变化时，setup 函数会重新执行以获取最新的值。context 是一个普通的 JavaScript 对象，它暴露了 attrs、slots 和 emit 等组件上下文信息，这些在 Vue 2 中通过 this 访问的属性，在 setup 中需要通过 context 来访问，因为 setup 执行时组件实例尚未创建，this 并不可用。

setup() 函数的返回值决定了模板中可以访问的变量和方法。任何在 setup 中定义并返回的对象、函数或响应式数据，都可以直接在组件的模板中使用。例如，我们可以返回一个包含响应式数据和方法的对象，模板就可以通过插值语法或事件绑定来直接使用它们。这种显式的返回机制使得组件的 API 更加清晰，开发者可以一目了然地知道哪些状态和行为是暴露给模板使用的。此外，Vue 3 还引入了 <script setup> 语法糖，它简化了 setup 函数的写法，使得在单文件组件中使用 Composition API 变得更加简洁和直观。在 <script setup> 中，所有顶层定义的变量和函数都会自动暴露给模板，无需手动返回，进一步提升了开发效率。

1.1.1 `setup()` 的执行时机与参数

setup() 函数的执行时机非常早，它在组件生命周期的 beforeCreate 钩子之前被调用，此时组件实例尚未完全创建，因此在 setup 内部无法访问 this 上下文。这个函数接收两个主要参数：props 和 context，并返回一个对象，该对象中的属性和方法将被暴露给组件的模板（template）使用。

props: 这是一个响应式的对象，包含了父组件传递给当前组件的所有属性。与 Vue 2 不同，这里的 props 是只读的，直接修改它不会触发更新，并且会在开发模式下收到警告。由于 props 是响应式的，你可以使用 watch 或 watchEffect 来监听其变化。
context: 这是一个普通的 JavaScript 对象，暴露了三个组件的 property：
- attrs: 包含了所有未在 props 中声明的属性（即非 prop 的 attribute）。与 props 不同，attrs 不是响应式的。
- slots: 一个插槽函数的对象，可以用来访问插槽内容。
- emit: 一个函数，用于触发自定义事件，向父组件传递数据。它等价于 Options API 中的 this.$emit 。

一个完整的 setup 函数签名示例如下：

import { defineComponent } from 'vue';

export default defineComponent({
  props: {
    message: String
  },
  setup(props, { attrs, slots, emit }) {
    console.log('Props:', props.message);
    console.log('Attrs:', attrs);
    console.log('Slots:', slots);
    console.log('Emit function:', emit);
    
    // ... 定义响应式数据、方法等
    
    return {
      // 返回要暴露给模板的属性和方法
    };
  }
});

通过这种方式，setup 函数为组件的逻辑提供了一个清晰、独立的入口点，使得代码组织更加模块化。

1.1.2 `setup()` 的返回值与模板访问

setup() 函数必须返回一个对象，这个返回的对象中的属性（包括响应式数据、计算属性、方法等）将会被合并到组件的渲染上下文中，从而可以在模板中直接使用。这是连接 Composition API 逻辑与组件视图的桥梁。例如，如果你在 setup 中定义了一个 ref 变量 count 和一个方法 increment，你需要在返回的对象中显式地包含它们，模板才能访问 {{ count }} 和 @click="increment"。

除了返回一个对象，setup 函数还可以返回一个渲染函数（render function）。当返回渲染函数时，该函数将直接用于渲染组件的 DOM，此时不能再返回其他属性。这种方式提供了对渲染过程的完全控制，适用于需要高度动态渲染的场景。如果在这种情况下仍然需要向父组件暴露一些方法（例如，通过模板 ref 调用），可以使用 context 参数中的 expose 函数。expose 接收一个对象，该对象中定义的属性将被显式地暴露给组件实例，即使 setup 返回的是一个渲染函数。

import { h, ref } from 'vue';

export default {
  setup(props, { expose }) {
    const count = ref(0);
    const increment = () => count.value++;

    // 暴露 increment 方法给父组件
    expose({
      increment
    });

    // 返回一个渲染函数
    return () => h('div', count.value);
  }
};

这种灵活的返回机制使得 setup 函数既能满足常规的模板驱动开发，也能应对更复杂的、需要程序化控制渲染的需求。

1.2 响应式 API：`ref` 与 `reactive`

Vue 3 的响应式系统是其核心特性之一，而 ref 和 reactive 是 Composition API 中创建响应式数据的两个主要工具。它们都基于 ES6 的 Proxy 对象实现，能够拦截对数据的访问和修改，从而实现依赖收集和自动更新视图。尽管它们的目标相似，但在使用方式、适用场景和行为上存在显著差异。

1.2.1 `ref`：处理基本类型与引用类型

ref 函数用于创建一个响应式的引用（reference）。它可以将任何类型的值（包括基本类型如 string, number, boolean，以及引用类型如 object, array）包装成一个带有 .value 属性的响应式对象。当访问或修改 .value 时，Vue 的响应式系统会进行追踪和触发更新。

基本类型: 对于基本类型，ref 是实现响应式的唯一选择，因为 reactive 只能处理对象。
引用类型: ref 也可以处理对象和数组。当 ref 的值是一个对象时，Vue 会通过 reactive 自动将其转换为深层响应式代理。这意味着你可以直接修改嵌套对象的属性，并且这些修改会被检测到。

在 JavaScript 代码中，必须通过 .value 来访问或修改 ref 所包装的值。然而，在模板中，Vue 会自动“解包” ref，因此可以直接使用变量名，无需 .value 。

import { ref } from 'vue';

const count = ref(0); // 基本类型
const state = ref({ name: 'Vue' }); // 引用类型

console.log(count.value); // 0
count.value++;
console.log(state.value.name); // 'Vue'
state.value.name = 'Vue 3';

ref 的一个重要优势是，当你重新为 .value 赋一个新对象时，其响应性不会丢失，这与 reactive 的行为不同。

1.2.2 `reactive`：处理复杂对象

reactive 函数用于将一个普通对象转换为一个深层响应式的代理对象。与 ref 不同，reactive 直接作用于对象本身，返回的代理对象与原始对象不相等。对代理对象的任何属性（包括嵌套属性）的修改都会被 Vue 的响应式系统追踪。

reactive 非常适合用于管理复杂的状态对象，例如一个包含多个嵌套属性和数组的表单数据。它默认是深层响应的，这意味着对象内部的所有嵌套对象和数组都会被递归地转换为响应式代理。

import { reactive } from 'vue';

const formState = reactive({
  user: {
    name: '',
    age: null
  },
  preferences: ['reading', 'coding']
});

// 直接修改属性
formState.user.name = 'Alice';
formState.preferences.push('traveling');

然而，reactive 存在一些使用上的“陷阱”。最著名的一个是，如果你直接给 reactive 对象重新赋一个新对象，将会导致响应性丢失。例如 formState = newFormState 是无效的。此外，对 reactive 对象进行解构也会丢失响应性，因为解构出来的是普通变量，不再是代理对象的一部分。

1.2.3 `ref` 与 `reactive` 的核心区别与选择

ref 和 reactive 在设计哲学和使用体验上有根本的不同。官方文档和社区实践中，越来越倾向于推荐使用 ref 作为声明响应式状态的主要 API 。以下是它们的核心区别对比：

选择建议:

优先使用 ref: 由于 ref 的通用性和更少的“心智负担”，官方推荐将其作为默认选择。它能处理所有数据类型，并且在重新赋值时表现得更直观和安全。
谨慎使用 reactive: 仅在明确需要管理一个复杂的、结构不会整体替换的对象状态时使用。例如，一个大型表单或一个具有多个嵌套属性的配置对象。使用时必须时刻警惕重新赋值和解构带来的响应性丢失问题。

1.2.4 响应式对象的解构与 `toRefs`

解构是 JavaScript 中常用的操作，但在 Vue 3 的响应式系统中需要格外小心。无论是 ref 还是 reactive，直接解构都会导致响应性丢失。

解构 reactive 对象:

    const state = reactive({ count: 0, name: 'Vue' });
    let { count, name } = state; // ❌ 错误：count 和 name 现在是普通变量，与 state 断开连接
    count++; // 不会触发更新

为了解决这个问题，Vue 提供了 toRefs 函数。toRefs 将一个 reactive 对象转换为一个普通对象，该对象的每个属性都是一个指向原始对象相应属性的 ref。这样解构出来的属性就保持了响应性。

    import { reactive, toRefs } from 'vue';
    const state = reactive({ count: 0, name: 'Vue' });
    const { count, name } = toRefs(state); // ✅ 正确：count 和 name 是 ref
    count.value++; // 会触发更新

解构 ref 对象: 如果你有一个 ref 对象，其值是一个对象，解构其 .value 同样会丢失响应性。

    const stateRef = ref({ count: 0 });
    let { count } = stateRef.value; // ❌ 错误：count 是普通变量

同样，可以使用 toRefs 来处理 ref 的 .value。

    const stateRef = ref({ count: 0 });
    const { count } = toRefs(stateRef.value); // ✅ 正确

toRefs 是处理响应式对象解构的关键工具，它确保了在需要单独使用响应式对象的某些属性时，不会破坏其响应性连接。

1.3 生命周期钩子

Vue 3 的 Composition API 提供了一系列与 Options API 生命周期钩子相对应的函数，允许开发者在 setup() 函数中以更灵活的方式注册生命周期逻辑。这些钩子函数都以 on 开头，并且需要手动从 vue 包中导入。

1.3.1 Composition API 中的生命周期钩子列表

以下是 Composition API 中可用的生命周期钩子及其与 Options API 的对应关系：

值得注意的是，Vue 3 中没有 onBeforeCreate 和 onCreated 钩子。因为 setup() 函数本身就在这两个钩子之前执行，所以 setup() 中的代码逻辑就扮演了这两个钩子的角色。

1.3.2 在 `setup()` 中使用生命周期钩子

在 setup() 函数中使用生命周期钩子非常直观。你只需要导入相应的钩子函数，并传入一个回调函数，该回调函数将在生命周期事件发生时执行。

import { onMounted, onUnmounted, ref } from 'vue';

export default {
  setup() {
    const count = ref(0);
    let timer = null;

    onMounted(() => {
      console.log('组件已挂载');
      timer = setInterval(() => {
        count.value++;
      }, 1000);
    });

    onUnmounted(() => {
      console.log('组件即将卸载，清理定时器');
      if (timer) {
        clearInterval(timer);
      }
    });

    return { count };
  }
};

这种方式使得与特定逻辑相关的生命周期代码可以被组织在一起。例如，所有与数据获取相关的逻辑（包括 onMounted 中的初始获取和 onUnmounted 中的取消请求）都可以放在同一个 composable 函数中，极大地提高了代码的内聚性。

1.3.3 与 Options API 生命周期钩子的对应关系

从 Options API 迁移到 Composition API 时，生命周期钩子的转换非常直接。下表清晰地展示了它们之间的映射关系，帮助开发者快速适应新的 API 风格。

对于父子组件嵌套的情况，生命周期钩子的执行顺序在 Vue 3 中也发生了变化。在挂载阶段，父组件的 setup 和 onBeforeMount 会先执行，然后是子组件的相应钩子，最后是父组件的 onMounted。这与 Vue 2 中父组件 created 之后、子组件 mounted 之前执行父组件 beforeMount 的顺序有所不同。理解这些顺序变化对于调试和理解组件的渲染流程至关重要。

2. 与 Options API 的对比分析

Vue 3 的 Composition API 的引入，标志着 Vue 组件开发范式的一次重大变革。它并非旨在完全取代传统的 Options API，而是为了解决在构建大型、复杂应用时，Options API 所暴露出的代码组织、逻辑复用和类型支持等方面的局限性。两种 API 各有其适用场景和优劣势，理解它们之间的核心差异，对于开发者根据项目需求做出合理的技术选型至关重要。本章节将深入剖析 Composition API 相较于 Options API 的核心优势，分析各自的适用场景，并探讨从 Options API 向 Composition API 迁移的策略与路径。

2.1 Composition API 的核心优势

Composition API 的设计哲学在于通过函数组合的方式，将相关的逻辑代码聚合在一起，从而提升代码的可读性、可维护性和复用性。这种范式转变带来了多方面的显著优势，尤其是在处理复杂组件和大型项目时，其优越性愈发凸显。

2.1.1 更灵活的代码组织与逻辑复用

Options API 采用一种“分治”的代码组织方式，将组件的逻辑按照 data、methods、computed、watch 等选项进行分类。这种模式在小型组件中结构清晰，易于上手。然而，当一个组件的功能变得复杂，例如需要同时处理用户认证、数据获取和图表渲染等多个关注点时，其代码会分散在各个选项中，导致开发者需要在不同代码块之间频繁跳转，增加了认知负荷和维护难度。这种“逻辑碎片化”的问题使得理解和修改特定功能的代码变得异常困难。

Composition API 通过 setup() 函数彻底改变了这一现状。它允许开发者按照逻辑功能（即“关注点”）来组织代码，将与特定功能相关的所有状态、计算属性、方法和生命周期钩子都封装在一起。例如，可以将所有与用户相关的逻辑（如 user 状态、fetchUser 方法）提取到一个独立的 useUser 函数中，将订单相关的逻辑提取到 useOrders 函数中。这种“逻辑聚合”的方式使得代码结构更加清晰，每个功能模块都内聚在一个独立的函数中，极大地提高了代码的可读性和可维护性。

更重要的是，Composition API 为逻辑复用提供了强大而干净的机制——Composables。在 Options API 中，逻辑复用主要依赖于 Mixins，但 Mixins 存在诸多弊端，如命名冲突、数据来源不清晰（“隐式依赖”）以及多个 Mixins 之间可能产生意想不到的交互等问题。Composables 则是普通的 JavaScript 函数，它们通过组合 Vue 的响应式 API 来封装可复用的逻辑。每个 Composable 都是一个独立的、自包含的逻辑单元，其输入（参数）和输出（返回值）清晰明确，不存在命名冲突的风险，并且可以轻松地在不同组件之间共享和组合，实现了真正意义上的“组合式”开发。

2.1.2 更强大的 TypeScript 支持

虽然 Vue 2 的 Options API 可以与 TypeScript 结合使用，但其类型推断能力相对有限，尤其是在处理 this 上下文和复杂的组件选项时，往往需要开发者手动编写大量的类型声明，开发体验欠佳。Options API 的分散式结构使得类型系统难以准确地追踪跨选项的数据流和依赖关系，导致类型推断经常出现偏差或失效。

Composition API 从一开始就为 TypeScript 提供了卓越的支持。由于其基于函数组合的模式，类型推断变得异常简单和精确。当使用 ref、reactive、computed 等 API 时，TypeScript 能够自动推断出响应式数据的类型。例如，定义一个 const count = ref(0)，TypeScript 会自动推断出 count 的类型为 Ref<number>。同样，当定义一个 Composable 函数时，可以通过泛型参数和返回类型注解，清晰地定义其输入和输出的类型，从而获得完整的类型安全和智能提示。这种原生的、强大的 TypeScript 集成，不仅提升了开发效率和代码质量，也使得在大型项目中进行重构和维护变得更加安全和可靠。

2.1.3 更小的打包体积与性能优化

Composition API 在性能方面也带来了显著的优势，主要体现在更小的打包体积和更高效的运行时性能。首先，Composition API 是基于函数导入的，这意味着它非常利于 Tree-shaking。在构建过程中，未使用的 Composition API 函数（如未调用的 Composables）可以被构建工具（如 Vite 或 Webpack）自动识别并移除，从而显著减小最终生成的 JavaScript 包体积。相比之下，Options API 的选项式结构使得 Tree-shaking 难以实现，因为所有选项都作为对象的一部分被定义，构建工具无法轻易判断哪些选项被真正使用。

其次，Composition API 的响应式系统基于 ES6 的 Proxy 实现，相比 Vue 2 中基于 Object.defineProperty 的实现，具有更细粒度的依赖追踪能力。Proxy 可以拦截对象属性的读取和设置操作，从而精确地知道哪些组件或计算属性依赖于哪些数据。当数据发生变化时，Vue 可以只更新真正依赖于该数据的部分，避免了不必要的组件重新渲染，提升了应用的运行时性能。此外，通过 markRaw 等 API，开发者还可以显式地标记某些对象为非响应式，从而进一步减少响应式系统的开销。

2.2 适用场景分析

尽管 Composition API 带来了诸多优势，但这并不意味着它适用于所有场景。Options API 凭借其简单直观的结构，在某些情况下仍然是更好的选择。开发者需要根据项目的规模、复杂度、团队的技术栈以及开发周期等因素，综合评估并做出决策。

2.2.1 何时选择 Composition API

根据多方实践经验和社区共识，Composition API 在以下场景中展现出其不可替代的价值：

中大型项目：在大型应用中，组件逻辑通常非常复杂，涉及多个相互关联的功能模块。Composition API 的逻辑聚合能力能够将复杂的代码拆分成更小、更易于管理的单元，极大地提升了代码的可维护性和可扩展性。
需要高度复用逻辑的组件：如果项目中存在大量需要在不同组件间共享的业务逻辑（如用户认证、权限管理、数据获取等），使用 Composables 进行逻辑封装和复用，可以避免 Mixins 带来的各种问题，实现干净、高效的代码共享。
复杂状态管理需求：当组件内部的状态管理变得复杂，涉及多个相互依赖的响应式数据和计算属性时，Composition API 提供了一种更灵活、更强大的方式来组织和管理这些状态，使得状态流转更加清晰。
使用 TypeScript 的项目：对于追求极致类型安全和开发体验的团队，Composition API 提供的卓越 TypeScript 支持是其最大的优势之一。强大的类型推断和类型安全能够显著减少运行时错误，提升开发效率。
需要更好性能优化的场景：对于对包体积和运行时性能有较高要求的应用，Composition API 的 Tree-shaking 友好特性和更细粒度的响应式追踪，能够带来实实在在的性能提升。

2.2.2 何时选择 Options API

尽管 Composition API 是 Vue 3 的推荐方向，但 Options API 在以下场景中仍然具有其独特的优势：

小型项目或简单组件：对于功能简单、逻辑不复杂的组件，Options API 的结构清晰、易于理解，可以快速完成开发，无需引入 Composition API 的复杂性。
Vue 2 迁移项目：对于从 Vue 2 迁移过来的项目，如果团队对 Options API 非常熟悉，且项目时间紧迫，可以暂时保持原有的代码风格，采用渐进式迁移的策略，而不是一次性全部重构。
团队熟悉 Options API 且无复杂逻辑需求：如果团队成员对 Composition API 不熟悉，且项目本身没有复杂的逻辑复用和状态管理需求，那么继续使用 Options API 可以避免额外的学习成本，保证开发效率。
需要快速原型开发的场景：在进行快速原型设计或概念验证时，Options API 的简单直观可以帮助开发者快速搭建出可用的界面，而无需过多关注代码的组织和结构。

2.2.3 混合使用两种 API 的策略

Vue 3 的一个巨大优势在于它完全支持在同一个项目中混合使用 Options API 和 Composition API。这种灵活性为开发者提供了平滑的迁移路径和根据具体场景选择最合适工具的自由。例如，可以在新开发的复杂组件中优先使用 Composition API，而对于一些简单的、已有的组件，则可以暂时保留其 Options API 的写法。

在一个组件内部，也可以实现两种 API 的共存。setup() 函数返回的对象中的属性和方法，可以在组件的 methods、computed 等其他选项中通过 this 上下文访问到。这意味着可以逐步地将一个复杂组件的逻辑从 methods 或 computed 中迁移到 setup() 函数中，而无需一次性重写整个组件。这种混合使用的策略，使得从 Options API 到 Composition API 的过渡可以是一个渐进、低风险的过程，极大地降低了迁移的门槛和成本。

2.3 从 Options API 迁移到 Composition API

对于许多现有的 Vue 2 或早期 Vue 3 项目，从 Options API 迁移到 Composition API 是一个需要谨慎规划和执行的过程。Vue 官方和社区提供了一系列策略和工具，以帮助开发者平滑地完成这一过渡。

2.3.1 迁移策略与步骤

迁移过程应遵循“渐进式”的原则，避免一次性大规模重构带来的风险和工作量。推荐的迁移策略包括：

在新组件中优先使用 Composition API：对于项目中新增的功能模块或组件，应直接采用 Composition API 进行开发。这不仅可以利用其带来的所有优势，还能让团队成员在实践中逐步熟悉新的开发范式。
逐步重构复杂旧组件：识别出项目中逻辑最复杂、维护最困难的组件，优先对这些组件进行重构。将其中可复用的逻辑提取为 Composables，将组件内部的逻辑按功能进行聚合。这种“由难到易”的重构方式，能够最大化地体现 Composition API 的价值。
使用 Composition API 封装可复用逻辑：将项目中通过 Mixins 或其他方式共享的逻辑，逐步迁移到 Composables 中。这可以作为一个独立的、低风险的重构任务，完成后，所有组件都可以受益于此。
利用迁移工具和兼容模式：对于 Vue 2 项目，可以使用 @vue/composition-api 插件，在 Vue 2 的环境中提前使用 Composition API。对于 Vue 3 项目，可以利用 Vue CLI 或 Vite 提供的迁移助手，辅助完成代码的转换。

2.3.2 常见迁移问题与解决方案

在迁移过程中，开发者可能会遇到一些常见问题，例如：

思维模式的转换：从 Options API 的“选项式”思维转换到 Composition API 的“函数式”思维，需要一定的时间。开发者需要习惯在 setup() 中组织所有逻辑，并理解 ref 的 .value 访问方式。
this 上下文的丢失：在 setup() 函数中，无法访问 this 上下文。所有需要在模板中使用的响应式数据、方法等，都必须显式地从 setup() 函数中返回。
生命周期钩子的变化：需要熟悉 Composition API 中 onMounted、onUnmounted 等生命周期钩子的用法，并理解它们与 Options API 中对应钩子的执行时机关系。

解决这些问题的关键在于充分理解 Composition API 的设计理念和核心概念，并通过实践不断加深理解。官方文档和社区的最佳实践文章是解决问题的宝贵资源。

3. 实际应用与最佳实践

掌握 Composition API 的核心概念只是第一步，更重要的是如何在实际项目中应用它，并遵循一套行之有效的最佳实践，以编写出优雅、高效、可维护的代码。本章节将深入探讨在项目中如何组织代码、如何创建和使用可复用的逻辑 Composables，以及如何避免常见的陷阱。

3.1 项目中的代码组织方式

Composition API 的核心优势之一在于其灵活的代码组织能力。通过合理的组织方式，可以将复杂的组件逻辑拆分成清晰、独立的模块，从而提升代码的可读性和可维护性。

3.1.1 模块化代码组织

在 Composition API 中，最推荐的代码组织方式是“按功能拆分”。不要将所有逻辑都堆砌在 setup() 函数中，这会使其变得臃肿且难以阅读。相反，应该将与特定功能相关的所有逻辑（包括状态、计算属性、方法、生命周期钩子等）提取到一个独立的函数中。这种函数通常被称为“组合式函数”或“Composable” 。

例如，一个复杂的用户仪表盘组件可能包含用户信息显示、数据图表渲染和实时通知等多个功能。我们可以将这些功能分别封装在 useUserInfo、useChartData 和 useNotifications 等独立的 Composables 中。在组件的 setup() 函数中，我们只需导入并调用这些 Composables，然后将它们返回的对象合并后暴露给模板即可。这种方式使得每个功能模块都高度内聚，组件的主 setup() 函数则变得非常简洁，只负责组合这些功能模块。

3.1.2 逻辑关注点分离

逻辑关注点分离是模块化代码组织的直接体现。其核心思想是，将与同一业务逻辑相关的代码放在一起，而不是按照技术类型（如 data、methods）进行划分。在 Options API 中，一个功能的实现可能需要在 data 中定义状态，在 methods 中定义方法，在 computed 中定义计算属性，代码被分散在组件的不同部分。而在 Composition API 中，所有这些都可以被封装在一个 Composable 函数中。

例如，一个“搜索”功能，可以创建一个 useSearch Composable，其中包含 searchTerm（响应式状态）、searchResults（计算属性）、performSearch（方法）以及用于监听 searchTerm 变化的 watch 逻辑。当组件需要使用搜索功能时，只需调用 useSearch() 即可。这种方式使得“搜索”这一逻辑关注点被完整地封装起来，无论是理解、修改还是复用，都变得异常简单。

3.1.3 单一职责原则

在创建 Composables 时，应遵循单一职责原则（Single Responsibility Principle），即每个 Composable 应该只负责一个特定的功能。一个 Composable 不应该既处理用户认证，又处理数据获取。如果一个 Composable 变得过于复杂，应该考虑将其进一步拆分成更小、更专注的 Composables。

例如，useUser Composable 应该只负责与用户状态相关的逻辑，如获取用户信息、更新用户资料等。如果还需要处理用户的订单，应该创建另一个独立的 useUserOrders Composable。遵循单一职责原则，可以确保每个 Composable 的功能清晰、易于测试和维护，也使得它们之间的组合更加灵活。

3.2 创建可复用的逻辑 Composables

Composables 是 Composition API 的灵魂，是实现逻辑复用的核心机制。它们是封装了特定功能的、可复用的函数，是构建复杂 Vue 应用的基石。

3.2.1 什么是 Composables

Composables 是一个利用 Vue 3 的 Composition API 来封装和复用有状态逻辑的函数。它通常以 use 作为函数名的前缀，例如 useCounter、useFetch、useAuth 等。一个 Composables 函数内部可以包含响应式状态（ref、reactive）、计算属性（computed）、监听器（watch）、生命周期钩子（onMounted）等任何 Composition API 提供的功能。

Composables 的核心价值在于，它将组件中与特定功能相关的逻辑提取出来，形成一个独立的、可移植的单元。这使得相同的逻辑可以在多个组件之间轻松共享，而无需复制粘贴代码，也避免了 Mixins 带来的命名冲突和来源不明等问题。

3.2.2 如何创建与使用 Composables

创建一个 Composables 非常简单，它就是一个普通的 JavaScript 函数，内部使用 Composition API 来实现特定功能，并最终返回一个包含响应式状态和方法的对象。

示例：创建一个 useCounter Composable

// composables/useCounter.js
import { ref, computed } from 'vue'

export function useCounter(initialValue = 0) {
  const count = ref(initialValue)
  const doubleCount = computed(() => count.value * 2)

  function increment() {
    count.value++
  }

  function decrement() {
    count.value--
  }

  function reset() {
    count.value = initialValue
  }

  return {
    count,
    doubleCount,
    increment,
    decrement,
    reset
  }
}

在组件中使用 useCounter

<template>
  <div>
    <p>Count: {{ count }}</p>
    <p>Double: {{ doubleCount }}</p>
    <button @click="increment">+</button>
    <button @click="decrement">-</button>
    <button @click="reset">Reset</button>
  </div>
</template>

<script setup>
import { useCounter } from '@/composables/useCounter'

const { count, doubleCount, increment, decrement, reset } = useCounter(10)
</script>

在这个例子中，useCounter Composable 封装了计数器的所有逻辑。任何需要使用计数器功能的组件，只需导入并调用 useCounter() 即可。每次调用都会创建一个新的、独立的计数器实例，保证了组件之间的状态隔离。

3.2.3 Composables 的约定与最佳实践

为了使 Composables 更易于理解和使用，社区形成了一套约定和最佳实践：

命名约定：Composables 的函数名应以 use 开头，这是一种约定俗成的规范，可以清晰地表明这是一个 Composable 函数。
返回值：Composables 应该返回一个包含所有需要暴露给外部使用的响应式数据和方法的普通对象。建议使用 ref 来定义返回的响应式变量，因为 reactive 对象在解构时会丢失响应性，而 ref 则不会。
参数：Composables 可以接受参数，用于初始化其内部状态或配置其行为。例如，useCounter 可以接受一个 initialValue 参数。
状态共享：默认情况下，每次调用 Composable 都会创建一个新的状态实例。如果需要实现跨组件的状态共享（即单例模式），可以将响应式状态定义在 Composable 函数的外部。这样，所有调用该 Composable 的组件将共享同一个状态。
处理副作用：如果 Composable 中包含了副作用（如事件监听、定时器、异步请求等），务必在 onUnmounted 或 onBeforeUnmount 钩子中进行清理，以防止内存泄漏。

3.2.4 Composables 与 Mixins 的对比

Composables 是 Vue 3 中推荐的逻辑复用方式，它在设计上彻底解决了 Vue 2 中 Mixins 存在的诸多问题。

| 特性 | Mixins (Vue 2) | Composables (Vue 3) |
| :--- | :--- | :--- |
| 命名冲突 | 多个 mixins 或 mixin 与组件自身的属性/方法名冲突时，后者会覆盖前者，导致难以追踪的 bug。 | 不存在命名冲突。Composables 返回的对象属性名由使用方决定，可以通过解构重命名来避免冲突。 |
| 数据来源 | 数据来源不清晰。使用 mixin 后，组件的选项中会出现来自 mixin 的属性和方法，开发者难以快速判断其来源。 | 数据来源清晰。通过 import { useXxx } from '...' 和 const { ... } = useXxx()，逻辑的来源一目了然。 |
| 逻辑复用 | 逻辑是“混入”到组件选项中的，仍然是分散的。 | 逻辑是“组合”在一起的，高度内聚。一个功能的所有逻辑都在一个函数中。 |
| 类型支持 | 对 TypeScript 的支持较差，类型推断困难。 | 对 TypeScript 提供了卓越的支持，类型推断清晰、准确。 |
| 灵活性 | 只能在组件选项层面进行合并，灵活性有限。 | 可以在 setup() 函数中灵活地调用，可以根据条件动态地使用不同的 Composables，甚至可以传递参数来定制 Composable 的行为。 |

综上所述，Composables 在逻辑复用方面全面优于 Mixins，是 Vue 3 项目中实现代码复用的首选方案。

3.3 常见陷阱与技巧

尽管 Composition API 功能强大，但在使用过程中也存在一些容易踩的“坑”。了解这些常见陷阱并掌握相应的技巧，可以帮助开发者编写出更健壮的代码。

3.3.1 响应式数据管理的陷阱

在响应式数据管理中，一个最常见的陷阱是关于 reactive 对象的解构。reactive 返回的是一个代理对象，其响应性依赖于这个代理。如果直接对 reactive 对象进行解构，例如 const { name, age } = reactive({ name: 'John', age: 30 })，那么解构出来的 name 和 age 将变成普通的字符串和数字，失去了响应性。当 name 或 age 的值发生变化时，模板将不会自动更新。

为了解决这个问题，Vue 3 提供了 toRefs 工具函数。toRefs 可以将一个 reactive 对象的所有属性都转换成 ref，这样解构出来的每个属性就都是响应式的了。

import { reactive, toRefs } from 'vue';

export default {
  setup() {
    const state = reactive({
      name: 'John',
      age: 30
    });

    // ❌ 错误：直接解构会失去响应性
    // const { name, age } = state;

    // ✅ 正确：使用 toRefs 保持响应性
    const { name, age } = toRefs(state);

    const updateName = () => {
      name.value = 'Jane'; // 模板会正确更新
    };

    return {
      name,
      age,
      updateName
    };
  }
};

另一个技巧是关于 ref 和 reactive 的选择。虽然两者都可以创建响应式数据，但它们有各自的最佳使用场景。ref 更通用，可以处理基本类型（如 string, number）和对象引用。而 reactive 则更适合用于管理具有多个属性的复杂对象。一个常见的最佳实践是：对于基本类型，始终使用 ref；对于复杂的对象结构，可以使用 reactive，但在需要解构其属性时，务必使用 toRefs 。

3.3.2 生命周期钩子的使用技巧

在 setup() 函数中，生命周期钩子的使用方式与 Options API 有所不同。它们被导入为独立的函数，并且需要在 setup() 的同步执行阶段被调用。

在 setup() 中注册：所有的 Composition API 生命周期钩子（如 onMounted, onUnmounted）都必须在 setup() 函数的执行期间被同步调用。不能在异步操作（如 await 之后）或回调函数中调用它们，因为此时组件的实例已经创建完成，无法再注册新的钩子。

    import { onMounted } from 'vue';

    export default {
      async setup() {
        // ❌ 错误：在 await 之后调用
        const data = await fetchData();
        onMounted(() => {
          console.log('This will not be registered correctly.');
        });

        // ✅ 正确：在同步代码中调用
        onMounted(() => {
          console.log('Component is mounted.');
        });

        return { data };
      },
    };

组合使用：可以在一个 setup() 函数中多次调用同一个生命周期钩子。Vue 会按照它们被调用的顺序来执行。这在需要将不同逻辑模块的初始化或清理代码分离开来时非常有用。

    import { onMounted } from 'vue';
    import { useUser } from '@/composables/useUser';
    import { useOrders } from '@/composables/useOrders';

    export default {
      setup() {
        const { fetchUser } = useUser();
        const { loadOrders } = useOrders();

        onMounted(() => {
          console.log('Initializing user module...');
          fetchUser();
        });

        onMounted(() => {
          console.log('Initializing orders module...');
          loadOrders();
        });
      },
    };

3.3.3 副作用管理与清理

在组件中执行副作用（如设置定时器、添加事件监听器、发起网络请求等）是常见的需求。Composition API 提供了强大的机制来管理这些副作用，并确保在组件卸载时进行适当的清理，以防止内存泄漏。

使用 onUnmounted 进行清理：任何在 onMounted 或其他钩子中创建的、需要手动清理的资源，都应该在 onUnmounted 或 onBeforeUnmount 中进行清理。

    import { onMounted, onUnmounted } from 'vue';

    export default {
      setup() {
        let timerId;

        onMounted(() => {
          timerId = setInterval(() => {
            console.log('Timer tick...');
          }, 1000);
        });

        onUnmounted(() => {
          // ✅ 正确：清理定时器
          clearInterval(timerId);
        });
      },
    };

watchEffect 的自动清理：watchEffect 函数在追踪其内部使用的响应式依赖时，会自动收集并执行副作用。更重要的是，它会在下一次副作用执行前或组件卸载时，自动调用其返回的清理函数。这使得管理异步操作（如网络请求）变得更加方便。

    import { ref, watchEffect } from 'vue';

    export default {
      setup() {
        const userId = ref(1);

        watchEffect((onInvalidate) => {
          const controller = new AbortController();
          
          fetch(`/api/user/${userId.value}`, { signal: controller.signal })
            .then(res => res.json())
            .then(data => console.log(data));

          // ✅ 正确：提供一个清理函数
          onInvalidate(() => {
            // 当 userId 改变或组件卸载时，会中止之前的请求
            controller.abort();
          });
        });

        return { userId };
      },
    };

3.3.4 TypeScript 集成与类型定义

Composition API 从设计之初就充分考虑了对 TypeScript 的支持，使得在 Vue 3 中编写类型安全的代码变得前所未有的简单和强大。

为 ref 和 reactive 定义类型：可以使用泛型来明确 ref 或 reactive 所包装的数据类型。

    import { ref, reactive } from 'vue';

    interface User {
      id: number;
      name: string;
      email: string;
    }

    export default {
      setup() {
        // ✅ 为 ref 定义类型
        const user = ref<User | null>(null);

        // ✅ 为 reactive 定义类型
        const formState = reactive<{
          username: string;
          password: string;
        }>({
          username: '',
          password: '',
        });

        return { user, formState };
      },
    };

为 Composables 定义类型：为 Composables 的参数和返回值定义类型，可以极大地提升其可维护性和使用体验。

    // src/composables/useCounter.ts
    import { Ref } from 'vue';

    // 定义返回对象的类型
    interface UseCounterReturn {
      count: Ref<number>;
      increment: () => void;
      decrement: () => void;
    }

    export function useCounter(initialValue: number): UseCounterReturn {
      const count = ref(initialValue);
      const increment = () => count.value++;
      const decrement = () => count.value--;
      return { count, increment, decrement };
    }

通过这种方式，当在其他组件中使用 useCounter 时，TypeScript 编译器和 IDE 能够提供完整的类型检查和智能提示，包括参数类型、返回值属性的类型等，从而有效减少运行时错误，并提升开发效率。