[!info] related notes

• 所属 MOC: Vue MOC
• 对比双方: Composition API, Options API
• 响应式基础: Vue 响应式系统

Vue Composition API vs Options API

一句话关系

两者都能写 Vue 组件，但组织代码的主轴不同：

Options API
→ 按 data / methods / computed / watch / lifecycle 等选项组织

Composition API
→ 按一个功能所需的 state / computed / effect / lifecycle 聚合

这不是“旧 API vs 新 API”的简单替代关系。

Options API 的组织模型

Options API 给组件提供稳定栏目：

• data
• computed
• methods
• watch
• lifecycle hooks

优势是结构约束强、上手直观。

当组件较小或中等复杂时：

“这段代码属于哪个 option？”

往往很容易回答。

Composition API 的组织模型

Composition API 使用：

• ref / reactive
• computed
• watch / watchEffect
• lifecycle functions
• provide / inject
• composables

核心变化是：

把同一功能相关的状态、派生、动作和生命周期放在一起。

在 SFC 中通常与 <script setup> 配合。

逻辑复用

Options API 历史上常用 mixin / extends 等方式复用逻辑。

Composition API 更倾向：

function useSearch() {
  ...
}

即 composable。

它的优势是：

• dependency 更显式；
• 来源更容易追踪；
• 类型更自然；
• 不容易出现 mixin 命名冲突。

TypeScript

Vue 官方当前明确指出，Composition API 通常具有更简单、有效和稳健的类型推导。

原因不是“Composition API 才支持 TS”，而是：

普通变量、函数与 imported APIs 更贴近 TypeScript 自身的推导模型。

Options API 同样支持 TypeScript。

大型组件为什么更常选择 Composition API

大型组件中一个功能可能同时需要：

state
computed
watch
request
lifecycle
event handler

Options API 会让它们分散到多个 option。

Composition API 可以按 feature 聚合。

但这不保证代码自动变好：

如果把所有内容都堆进一个巨大 setup/script setup，同样会失去结构。

真正目标是进一步拆 composable 和 domain boundary。

Options API 没有被废弃

Vue 官方没有计划废弃 Options API。

它仍然适合：

• 小到中型组件；
• 更偏声明式的团队；
• 已有稳定 Options API codebase；
• 不需要复杂逻辑抽取的页面。

不要为了“Vue3 就必须 Composition API”机械重写稳定代码。

可以混用吗

可以。

例如已有 Options API 组件可以通过 setup() 集成 Composition API 逻辑。

但新代码长期混合两套风格会增加认知成本，所以团队通常应有主风格。

选择模型

优先考虑 Composition API：

• TypeScript 为主；
• 复杂业务组件；
• 大量逻辑复用；
• composable 生态；
• 希望按功能组织。

Options API 仍然合理：

• 组件较小；
• 现有代码稳定；
• 团队熟悉 option-based organization；
• 不需要复杂抽取。

学习检查

1. Composition API 与 Options API 最核心的组织维度差异是什么？
2. 为什么 Composition API 更适合 composable？
3. 为什么 TypeScript 优势不等于“Options API 不支持 TS”？
4. Vue3 为什么不能简单理解成“Composition API 取代 Options API”？
5. 一个 500 行复杂表单，用两种 API 分别会怎样组织同一功能的 state/watch/method？
6. 什么情况下你不会为了统一风格重写已有 Options API 组件？
7. Composition API 代码很乱时，真正该拆的通常是什么？