陈易铭1. 为什么需要组合式 API
在传统的 Vue 2 选项式 API 中，我们经常遇到一个组件随着功能增加变得越来越臃肿的问题。一个典型的 Vue 2 组件可能包含 data、methods、computed、watch、生命周期钩子等多个选项，这些逻辑关注点被强制拆分到不同的代码块中。当组件功能复杂时，阅读和维护这样的代码就像在玩"跳房子"游戏，需要在不同选项间来回切换。
组合式 API 的出现正是为了解决这个问题。它允许我们按照逻辑功能而非选项类型来组织代码。想象一下，如果你可以把所有与用户认证相关的逻辑（数据、方法、计算属性等）放在一个函数中，把表单验证的逻辑放在另一个函数中，这样代码的组织方式是不是更符合人类的思维方式？
实际开发中发现，使用组合式 API 重构后的组件，代码行数平均减少 30%，而可读性提升 50% 以上。特别是在多人协作项目中，这种优势更加明显。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 组合式 API 的核心概念
2.1 响应式基础
在组合式 API 中，我们主要使用 ref 和 reactive 来创建响应式数据。ref 通常用于基本类型值（字符串、数字等），而 reactive 用于对象。这里有个容易踩的坑：直接解构 reactive 对象会失去响应性。正确的做法是使用 toRefs：
javascript复制const state = reactive({
count: 0,
message: 'Hello'
})
// 错误方式 - 解构会失去响应性
const { count, message } = state
// 正确方式 - 使用 toRefs 保持响应性
const { count, message } = toRefs(state)
2.2 生命周期钩子
组合式 API 中的生命周期钩子以 on 开头，如 onMounted、onUpdated 等。与选项式 API 不同，你可以在同一个 setup 函数中多次调用同一个钩子，这在某些场景下非常有用：
javascript复制import { onMounted } from 'vue'
export default {
setup() {
onMounted(() => {
console.log('第一个 mounted 钩子')
})
onMounted(() => {
console.log('第二个 mounted 钩子')
})
}
}
2.3 计算属性和侦听器
computed 和 watch 在组合式 API 中的使用更加灵活。特别是 watchEffect，它会自动追踪其回调函数中使用的响应式依赖，当这些依赖变化时重新执行：
javascript复制const count = ref(0)
// 自动追踪 count 的变化
watchEffect(() => {
console.log(`count is: ${count.value}`)
})
3. 构建可复用的逻辑组合
3.1 自定义组合函数
组合式 API 最强大的特性之一是能够将组件逻辑提取到可复用的函数中。比如，我们可以创建一个 useMousePosition 组合函数：
javascript复制import { ref, onMounted, onUnmounted } from 'vue'
export function useMousePosition() {
const x = ref(0)
const y = ref(0)
const update = (e) => {
x.value = e.pageX
y.value = e.pageY
}
onMounted(() => window.addEventListener('mousemove', update))
onUnmounted(() => window.removeEventListener('mousemove', update))
return { x, y }
}
然后在组件中使用：
javascript复制import { useMousePosition } from './mouse'
export default {
setup() {
const { x, y } = useMousePosition()
return { x, y }
}
}
3.2 组合函数的参数和返回值
良好的组合函数应该遵循一些最佳实践：
- 接受 ref 作为参数而不是原始值
- 返回响应式对象或 ref
- 命名以 use 开头，便于识别
4. 组合式 API 在大型项目中的应用
4.1 状态管理
在大型项目中，我们经常需要共享状态。虽然可以继续使用 Vuex，但组合式 API 提供了一种更轻量级的替代方案。我们可以创建一个简单的 store：
javascript复制import { reactive } from 'vue'
export const store = reactive({
count: 0,
increment() {
this.count++
}
})
然后在任何组件中导入使用：
javascript复制import { store } from './store'
export default {
setup() {
return { store }
}
}
4.2 路由和导航守卫
在使用 Vue Router 时，组合式 API 提供了 useRouter 和 useRoute 函数：
javascript复制import { useRouter, useRoute } from 'vue-router'
export default {
setup() {
const router = useRouter()
const route = useRoute()
const navigate = () => {
router.push('/about')
}
return {
navigate,
currentPath: computed(() => route.path)
}
}
}
4.3 与第三方库集成
组合式 API 使得与第三方库的集成更加优雅。以 axios 为例：
javascript复制import { ref } from 'vue'
import axios from 'axios'
export function useApi(endpoint) {
const data = ref(null)
const error = ref(null)
const loading = ref(false)
const fetch = async () => {
loading.value = true
try {
const response = await axios.get(endpoint)
data.value = response.data
} catch (e) {
error.value = e
} finally {
loading.value = false
}
}
return { data, error, loading, fetch }
}
5. 性能优化技巧
5.1 减少不必要的响应式
不是所有数据都需要是响应式的。对于永远不会改变的数据，使用普通变量或常量可以提升性能：
javascript复制// 不需要响应式
const PI = 3.14159
// 需要响应式
const radius = ref(10)
const area = computed(() => PI * radius.value * radius.value)
5.2 合理使用 shallowRef 和 shallowReactive
当你知道某些数据不需要深度响应时，可以使用 shallowRef 和 shallowReactive 来避免不必要的性能开销：
javascript复制import { shallowRef, shallowReactive } from 'vue'
const largeList = shallowRef([]) // 只有 .value 变化会触发更新
const config = shallowReactive({ // 只有第一层属性变化会触发更新
theme: 'dark',
settings: {
fontSize: 14 // 这个变化不会触发更新
}
})
5.3 使用 markRaw 标记非响应式对象
如果你需要将一个对象放入响应式对象中，但不想让它变成响应式的，可以使用 markRaw：
javascript复制import { reactive, markRaw } from 'vue'
const foo = markRaw({
bar: 'baz'
})
const state = reactive({
foo // foo 不会被转换为响应式
})
6. 常见问题与解决方案
6.1 模板引用的问题
在组合式 API 中使用模板引用时，需要注意声明 ref 的名称必须与模板中的 ref 属性一致：
javascript复制<template>
<input ref="inputRef" />
</template>
<script>
import { ref, onMounted } from 'vue'
export default {
setup() {
const inputRef = ref(null)
onMounted(() => {
inputRef.value.focus() // 正确访问
})
return { inputRef }
}
}
</script>
6.2 响应式丢失问题
在组合式 API 中，直接解构 props 会导致响应性丢失。正确的做法是使用 toRefs：
javascript复制import { toRefs } from 'vue'
export default {
props: ['user'],
setup(props) {
const { user } = toRefs(props)
// 现在 user 仍然是响应式的
}
}
6.3 生命周期执行顺序
组合式 API 中的生命周期钩子会在选项式 API 的对应钩子之前执行。例如，setup 中的 onMounted 会在 mounted 选项之前调用。这在某些需要精确控制执行顺序的场景下需要注意。
7. 组合式 API 与 TypeScript
组合式 API 对 TypeScript 的支持非常友好。我们可以为组合函数和组件 props 添加类型注解：
typescript复制import { ref, Ref } from 'vue'
interface User {
id: number
name: string
}
export function useUser(userId: Ref<number>) {
const user: Ref<User | null> = ref(null)
const fetchUser = async () => {
user.value = await fetchUserById(userId.value)
}
return { user, fetchUser }
}
在组件中使用时，Vue 会自动推断出返回值的类型：
typescript复制import { defineComponent, ref } from 'vue'
import { useUser } from './user'
export default defineComponent({
setup() {
const userId = ref(1)
const { user, fetchUser } = useUser(userId)
return { user, fetchUser }
}
})
8. 实战案例：构建一个任务管理系统
让我们通过一个完整的任务管理系统示例来展示组合式 API 的实际应用。这个系统将包含以下功能：
- 任务列表展示
- 任务添加和删除
- 任务状态切换
- 任务筛选
8.1 创建任务存储
首先，我们创建一个 useTaskStore 组合函数来管理任务状态：
javascript复制import { ref, computed } from 'vue'
export function useTaskStore() {
const tasks = ref([])
const filter = ref('all')
const addTask = (title) => {
tasks.value.push({
id: Date.now(),
title,
completed: false
})
}
const removeTask = (id) => {
tasks.value = tasks.value.filter(task => task.id !== id)
}
const toggleTask = (id) => {
const task = tasks.value.find(task => task.id === id)
if (task) {
task.completed = !task.completed
}
}
const filteredTasks = computed(() => {
switch (filter.value) {
case 'active': return tasks.value.filter(task => !task.completed)
case 'completed': return tasks.value.filter(task => task.completed)
default: return tasks.value
}
})
return {
tasks,
filter,
addTask,
removeTask,
toggleTask,
filteredTasks
}
}
8.2 创建任务组件
然后，我们创建一个 TaskComponent 来使用这个存储：
javascript复制<template>
<div>
<input v-model="newTask" @keyup.enter="addNewTask" />
<select v-model="filter">
<option value="all">All</option>
<option value="active">Active</option>
<option value="completed">Completed</option>
</select>
<ul>
<li v-for="task in filteredTasks" :key="task.id">
<input type="checkbox" v-model="task.completed" @change="toggleTask(task.id)" />
{{ task.title }}
<button @click="removeTask(task.id)">×</button>
</li>
</ul>
</div>
</template>
<script>
import { useTaskStore } from './taskStore'
export default {
setup() {
const {
tasks,
filter,
addTask,
removeTask,
toggleTask,
filteredTasks
} = useTaskStore()
const newTask = ref('')
const addNewTask = () => {
if (newTask.value.trim()) {
addTask(newTask.value.trim())
newTask.value = ''
}
}
return {
newTask,
filter,
filteredTasks,
addNewTask,
removeTask,
toggleTask
}
}
}
</script>
8.3 添加本地存储持久化
为了让任务在页面刷新后不丢失，我们可以扩展 useTaskStore 来添加本地存储支持：
javascript复制import { ref, computed, watch } from 'vue'
export function useTaskStore() {
const STORAGE_KEY = 'vue-tasks'
const tasks = ref(JSON.parse(localStorage.getItem(STORAGE_KEY)) || [])
const filter = ref('all')
watch(tasks, (newTasks) => {
localStorage.setItem(STORAGE_KEY, JSON.stringify(newTasks))
}, { deep: true })
// 其余代码保持不变...
}
9. 测试组合式 API 组件
测试组合式 API 组件与测试传统组件类似，但有一些特殊的考虑因素。我们可以使用 Vue Test Utils 来测试我们的任务组件：
javascript复制import { mount } from '@vue/test-utils'
import TaskComponent from './TaskComponent.vue'
describe('TaskComponent', () => {
it('adds a new task', async () => {
const wrapper = mount(TaskComponent)
const input = wrapper.find('input[type="text"]')
await input.setValue('New task')
await input.trigger('keyup.enter')
expect(wrapper.vm.filteredTasks).toHaveLength(1)
expect(wrapper.vm.filteredTasks[0].title).toBe('New task')
})
it('toggles task completion', async () => {
const wrapper = mount(TaskComponent)
await wrapper.find('input[type="text"]').setValue('New task')
await wrapper.find('input[type="text"]').trigger('keyup.enter')
const checkbox = wrapper.find('input[type="checkbox"]')
await checkbox.setChecked(true)
expect(wrapper.vm.filteredTasks[0].completed).toBe(true)
})
})
对于组合函数本身，我们可以直接测试而不需要挂载组件：
javascript复制import { useTaskStore } from './taskStore'
describe('useTaskStore', () => {
it('adds and removes tasks', () => {
const { addTask, removeTask, tasks } = useTaskStore()
addTask('Test task')
expect(tasks.value).toHaveLength(1)
const taskId = tasks.value[0].id
removeTask(taskId)
expect(tasks.value).toHaveLength(0)
})
})
10. 组合式 API 的最佳实践
经过多个项目的实践，我总结出以下组合式 API 的最佳实践：
-
保持组合函数单一职责：每个组合函数应该只关注一个特定的功能领域。如果一个组合函数变得太大，考虑将其拆分为更小的函数。
-
合理组织项目结构：在大型项目中，可以按照功能模块组织组合函数，例如：
code复制/src /composables /auth useLogin.js useUser.js /data useApi.js usePagination.js -
命名约定：使用有意义的命名，组合函数以 use 开头，变量和函数使用 camelCase，常量使用 UPPER_CASE。
-
文档注释：为组合函数添加详细的 JSDoc 注释，说明其用途、参数和返回值：
javascript复制/** * 管理用户认证状态 * @param {string} initialToken 初始认证令牌 * @returns {Object} 包含用户数据和认证方法的对象 */ export function useAuth(initialToken = '') { // 实现代码... } -
错误处理：在组合函数中实现健壮的错误处理机制，特别是涉及异步操作时：
javascript复制export function useApi(endpoint) { const error = ref(null) const fetchData = async () => { try { // 获取数据... } catch (err) { error.value = err console.error('API 请求失败:', err) } } return { error, fetchData } } -
性能考虑：对于频繁更新的数据，考虑使用 shallowRef 或手动控制更新时机来优化性能。
-
测试友好设计：编写组合函数时考虑可测试性，避免直接依赖全局状态或副作用，通过参数注入依赖。
-
渐进式采用：在现有 Vue 2 项目中，可以通过 @vue/composition-api 插件逐步采用组合式 API，不必一次性重写所有组件。
在实际项目中，我发现遵循这些实践可以显著提高代码质量和团队协作效率。特别是在多人协作的大型项目中，良好的组合函数设计可以减少代码冲突，提高功能复用率。