Vue 3 组合式 API 实战：从 Options API 到 Composition API 的平滑迁移

随着 Vue 3 的普及，组合式 API（Composition API）已经成为 Vue 生态中不可或缺的一部分。它带来了更灵活的逻辑组织方式，也让大型项目的可维护性有了显著提升。但很多开发者在从 Options API 迁移时，常常会感到困惑：到底该怎么写？哪些场景更适合组合式 API？

本文将从实战角度出发，对比两种写法，并分享一些迁移过程中的经验与坑点。

为什么需要组合式 API？

在 Options API 中，我们习惯把代码按选项分类：data、methods、computed、watch 等。当一个组件变得复杂时，同一个功能的逻辑会被拆散到不同选项中，导致阅读和維護成本上升。

举个例子：一个搜索框组件，需要维护搜索关键词、防抖、请求取消、结果缓存。在 Options API 中，这些逻辑可能分散在 data、methods、watch、beforeUnmount 里。而组合式 API 允许我们把相关逻辑写在一起，甚至抽成可复用的函数。

一个简单的对比

假设我们有一个计数器组件。

Options API 写法：

<template>
  <button @click="increment">{{ count }}</button>
</template>

<script>
export default {
  data() {
    return {
      count: 0
    }
  },
  methods: {
    increment() {
      this.count++
    }
  }
}
</script>

Composition API 写法：

<template>
  <button @click="increment">{{ count }}</button>
</template>

<script setup>
import { ref } from 'vue'

const count = ref(0)

function increment() {
  count.value++
}
</script>

看起来更简洁，但真正的威力在于逻辑复用。

逻辑复用：自定义 Hook

组合式 API 最大的优势之一是可以通过函数来复用逻辑。比如我们写一个 useCounter：

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

export function useCounter(initialValue = 0) {
  const count = ref(initialValue)

  function increment() {
    count.value++
  }

  function decrement() {
    count.value--
  }

  return {
    count,
    increment,
    decrement
  }
}

在组件中使用：

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

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

这种模式让逻辑与 UI 解耦，测试也更方便。

生命周期与副作用

组合式 API 中，生命周期钩子需要从 vue 中导入，并以 on 开头：

import { onMounted, onUnmounted } from 'vue'

onMounted(() => {
  console.log('组件挂载')
})

onUnmounted(() => {
  console.log('组件卸载')
})

对于副作用，比如事件监听、定时器，建议统一放在 onMounted 和 onUnmounted 中，避免内存泄漏。

常见坑点

1. ref 与 reactive 的选择
   ref 适合基本类型，reactive 适合对象。但 reactive 解构后会失去响应性，需要配合 toRefs 使用。

2. script setup 中的 this
script setup 中没有 this，所有变量和函数都直接暴露给模板。

3. watch 的写法变化
   组合式 API 中 watch 可以监听多个源，也可以使用 watchEffect 自动追踪依赖。

4. 模板引用
   使用 ref 获取 DOM 或组件实例时，需要在模板中绑定 ref，并在 script setup 中声明同名变量。

迁移策略

如果你的项目还在用 Options API，不必一次性重写。可以按以下步骤渐进迁移：

1. 新组件优先使用 <script setup>。
2. 老组件在修改时，逐步将逻辑抽成组合式函数。
3. 对于复杂的 Mixin，优先重构为组合式函数。
4. 保持团队代码风格一致，必要时制定规范。

总结

组合式 API 不是银弹，但它确实为 Vue 应用提供了更好的逻辑组织和复用能力。对于新项目，推荐直接使用 <script setup>；对于老项目，可以渐进式迁移。关键在于理解其设计思想：按逻辑关注点组织代码，而不是按选项类型。

希望这篇文章能帮助你更好地理解和使用 Vue 3 的组合式 API。如果你有迁移经验或踩坑故事，欢迎在评论区分享。