8.3 两种 API 优劣势对比与选型建议

Vue 3 同时支持选项式 API 和组合式 API 两种编写风格，这不是“旧版弃用、新版强推”的单选题，而是为不同场景提供最合适的工具。理解它们各自的优势与局限，才能在实际开发中作出务实选择。

选项式 API（Options API）

选项式 API 是 Vue 2 的唯一写法，在 Vue 3 中依旧完整支持。它的结构是将组件的配置项按类型分块：data、methods、computed、watch、props、emits、生命周期钩子等，每一项都是一个独立的选项对象。

典型代码结构：

export default {
  props: ['title'],
  data() {
    return {
      count: 0,
      user: null
    }
  },
  computed: {
    doubleCount() {
      return this.count * 2
    }
  },
  watch: {
    count(newVal) {
      console.log('count changed:', newVal)
    }
  },
  methods: {
    increment() {
      this.count++
    }
  },
  mounted() {
    this.fetchUser()
  }
}

优势：

结构清晰，约定俗成：同一个功能的代码虽然分散在不同选项中，但每种代码都有固定位置。对新手或从 Vue 2 迁移的开发者来说，“数据放 data，方法放 methods”几乎不需要额外思考。
上手心智负担低：学习路径线性明确，按选项逐个理解即可写出可用的组件。
适合简单组件：当组件逻辑不多、功能单一（如纯展示卡片、简单表单输入），选项式 API 的代码一目了然，不需要额外引入组合式 API 的概念。

劣势：

逻辑分散，维护成本随复杂度上升：当一个组件承载多个独立业务逻辑时（如用户信息编辑 + 权限校验 + 数据缓存），同一个逻辑的相关代码会散落在 data、computed、watch、mounted 等不同选项中。维护时需要纵向跳转，不利于快速理解一个完整功能。
逻辑复用困难：传统上通过 mixin 混入实现复用，但 mixin 存在命名冲突、来源不清晰、难以类型推导等问题，随着项目变大，mixins 的维护通常是一场噩梦。
TypeScript 支持有限：选项式 API 中 this 的类型推断不如组合式 API 精确，复杂类型推导时往往需要额外的手动注解。

组合式 API（Composition API）

组合式 API 通过 setup 函数（或 <script setup> 语法糖）提供一个统一的作用域，你可以按功能关注点来组织响应式状态、计算属性、侦听器和生命周期钩子。

典型代码结构（<script setup>）：

<script setup>
import { ref, computed, watch, onMounted } from 'vue'

const props = defineProps(['title'])
const count = ref(0)
const doubleCount = computed(() => count.value * 2)

watch(count, (newVal) => {
  console.log('count changed:', newVal)
})

function increment() {
  count.value++
}

onMounted(() => {
  fetchUser()
})
</script>

优势：

逻辑聚合，高内聚：同一个业务逻辑相关的状态、计算属性、方法、生命周期可以写在一起，甚至可以抽离成独立的组合函数（hooks）。阅读代码时不再需要跨选项跳转，维护更方便。
逻辑复用能力极强：将一组相关逻辑封装为自定义 hooks（如 useMouse()、useAuth()），在多个组件中零冲突地复用，且拥有完整的类型推导。这是组合式 API 最大的生产力提升。
更好的 TypeScript 支持：响应式变量直接就是带类型的引用，无需通过 this 访问，类型推断自然且准确。
灵活的代码组织：不受选项分块约束，可以按业务关注点任意组织代码块，对大型复杂组件尤其友好。

劣势：

初始学习曲线更高：需要理解 ref、reactive、setup 作用域、响应式引用 .value 等概念，写法上不如选项式 API 直观（例如必须用 count.value 而非 this.count）。
代码组织需要自律：没有了选项的物理约束，初学者可能写出杂乱无章的 setup 函数，将所有东西堆在一起而不进行合理拆分。团队需要建立自定义 hooks 拆分规范。
不适用于极端简的场景：对于只有两三个数据和一个方法的简单组件，组合式 API 的写法可能显得繁琐，选项式 API 反而更直接。

选型建议：没有银弹，按场景选择

在实际项目中，两种 API 可以并存——同一个项目里，复杂组件用组合式 API，简单组件用选项式 API，Vue 3 完全兼容。以下是基于团队经验和项目规模的选型参考：

| 场景 | 推荐 API | 原因 |
|------|----------|------|
| 学习 Vue 的新人 | 先选项式，再过渡到组合式 | 选项式结构清晰，能快速建立“数据-视图”的心智模型，熟悉后再接触组合式 API 更容易理解其优势。 |
| Vue 2 项目迁移到 Vue 3 | 混合使用，逐步替换 | 无需一次性重写所有组件，旧组件保持选项式，新功能用组合式 API，用 @vue/compat 平滑过渡。 |
| 中小型组件（逻辑简单） | 选项式 API | 如纯 UI 组件、简单的表单，选项式 API 代码量少，阅读直观。 |
| 大型复杂组件（多逻辑关注点） | 组合式 API | 如包含权限校验、数据缓存、实时同步、表单验证等多种逻辑的页面，组合式 API 能将每个关注点封装为独立 hooks。 |
| 需要大量逻辑复用的项目 | 组合式 API | 通过自定义 hooks 共享逻辑，避免 mixin 带来的命名冲突和来源不清问题。 |
| 强 TypeScript 项目 | 优先组合式 API | TS 支持更完善，类型推导流畅，代码健壮性更好。 |
| 团队习惯与规范 | 统一一种为主 | 为避免混乱，最好在项目级约定一种主流写法，推荐新项目默认使用 <script setup> 组合式 API，同时允许简单组件保留选项式。 |

一句话总结：选项式 API 是“好入门、易维护小组件”的稳妥选择；组合式 API 是“解决复杂逻辑组织和复用”的强大利器。从 Vue 3 的发展趋势和官方推荐来看，组合式 API 正逐渐成为主流写法，但它并不会让选项式 API 消失。选型时，优先考虑当前组件的复杂度和未来复用可能性，而不是非此即彼的教条。