引言

随着 Vue 3 的正式发布，Composition API（组合式 API）成为 Vue 生态中最受关注的特性之一。相比于 Vue 2 的 Options API，Composition API 提供了更灵活的逻辑组织方式和更好的代码复用能力，尤其适合中大型项目。然而，许多开发者在初次接触时，容易陷入“只是把 data 和 methods 搬到 setup 里”的误区。本文将从核心概念出发，结合贴近实际场景的完整代码示例，带你掌握 Composition API 的进阶用法与最佳实践，并探讨开发中常见的陷阱与解决方案。

一、核心概念：setup、响应式与组合逻辑

1.1 setup 函数：一切的入口

setup 是 Composition API 的起点，它在组件实例被创建之前执行，因此无法访问 this。setup 接收两个参数：props 和 context。你需要将模板中要使用的数据和方法通过返回对象的形式暴露出去。

<script>
export default {
  setup(props, context) {
    // 在这里组织所有逻辑
    const message = 'Hello Vue 3';
    return {
      message
    };
  }
};
</script>

1.2 响应式基石：ref 与 reactive

Vue 3 通过 Proxy 实现真正的响应式。ref 用于包装基本类型值（或对象），返回一个带有 .value 的响应式引用；reactive 则用于将对象整体变成响应式对象。

import { ref, reactive } from 'vue';

const count = ref(0);     // 访问需 .value
const state = reactive({
  name: 'Vue',
  version: 3
});
// 修改时自动触发更新
count.value++;
state.name = 'Vue 3';

关键区别：ref 会将内部值用对象包裹，而 reactive 可以直接操作属性；ref 可以重新赋值，reactive 重新赋值会丢失响应式；模板中 ref 会自动解包，无需 .value。

1.3 组合函数的魔力

Composition API 最大的优势在于可以将同一逻辑关注点的代码抽离成独立的组合函数（Composables），从而实现更高级别的复用。

二、实战示例：构建一个可搜索的用户列表

下面我们将构建一个完整的单文件组件，它包含数据获取、搜索过滤、加载状态、错误处理等常见需求。代码可以直接复制到 Vue 3 项目中运行，每部分都配有详细注释。

```vue