干了几年 Vue 项目从 2.x 一路用到 3.x最深的感受就是组合式 API 这玩意儿用好了是真省心用不好就是大型翻车现场。今天这篇不聊基础语法直接聚焦组合式 API 在真实业务工程中的最佳实践把我自己在订单中台、权限系统、数据报表这几个项目里踩过的坑、沉淀下来的套路一次性讲透。适合正在做中大型 Vue 3 项目、或者准备从 Options API 迁移重构的团队参考。文章里会涉及自定义组合式函数的封装原则、生命周期资源回收、类型安全、与 Pinia 的边界划分、实操抽取案例以及一套可以直接抄的团队规范清单全部基于真实业务场景不是教材式讲解。1. 组合式 API 的核心思路与设计拆解1.1 为什么大型项目更需要组合式 API先说一个大多数团队都会遇到的痛点。用 Options API 写业务一个稍微复杂点的页面data、computed、methods、watch 四个区域各写各的同一个业务功能的数据却散落在四个地方。比如一个订单列表页搜索条件在 data筛选逻辑在 computed表格数据请求在 methods监听翻页的 watch 在 watch 区。你要理解这个页面的完整逻辑得在四个区块之间反复跳转代码超过 300 行之后这种心智负担就很明显了。组合式 API 解决的正是这个问题——它把“功能”而非“代码类型”作为组织单位。一个业务功能相关的状态、计算属性、方法、副作用全部收拢在一个函数或者一个模块里形成独立逻辑单元。这在小型 demo 里感知不强但到了大型项目逻辑单元边界清晰之后复用、测试、排错、多人协作的效率差距会非常明显。我见过不少团队做迁移的时候只是把 setup 当作一个更大的“mounted”或者“data”来用本质上还是 Options API 的写法换了个壳所有逻辑依然堆在 setup 函数里。这种用法不要说最佳实践连组合式 API 的基本价值都没有发挥出来。真正合理的做法是setup 只做组合编排具体逻辑下沉到独立的组合式函数Composable中。1.2 组合式 API 的逻辑单元划分原则判断一个逻辑单元划分得好不好我习惯问三个问题这个逻辑单元能不能被独立复用哪怕是另一个页面稍微改改参数就能用这个逻辑单元能不能脱离组件单独测试我不需要挂载组件就能验证它的行为这个逻辑单元内部的状态变更是不是只围绕同一个业务目标举个例子订单列表页包含的“分页逻辑”“筛选表单逻辑”“表格数据请求逻辑”“导出逻辑”这些都是独立业务目标应该拆成独立的组合式函数。对比之下很多新手会把“订单相关的所有东西”塞进一个大函数里面既有分页又有关单又有导出看起来是组合式 API实际上只是把一个大组件变成了一个大函数复用、测试依然是零。核心原则就是按业务能力切分不按业务对象切分。还有一个容易被忽视的点组合式函数内部的职责是“管理状态与副作用”不是“执行业务动作”。比如 useOrderList 只负责管好列表数据、loading、分页状态至于点击导出按钮怎么拼接参数、怎么调导出接口那是更上层编排的事不应该塞进 useOrderList 里。1.3 常见的错误用法与反面案例组合式 API 常见的翻车姿势我基本都见过列几个典型的。第一种是把所有东西塞进 setup。setup里写了一百行代码ref 定义十几个watch 挂三个最后 return 一大坨给模板。这比 Options API 还难读因为连“data 和 methods 至少是分开的”这种基本结构都没了。第二种是在模块作用域创建共享状态。这个坑非常隐蔽// 错误示范 const page ref(1); const tableData ref([]); export function useOrderList() { // 直接操作顶层 ref return { page, tableData }; }第一次调用这个函数时感觉一切正常但当你同时在一个页面里用两个订单列表比如“全部订单”和“退款订单”两个 tab或者多个组件同时调用这个函数时所有实例共享同一份page和tableData状态就会互相串。这就是为什么组合式函数内部的响应式状态必须在函数内部创建每次调用都生成新实例。第三种是过度抽象。有些同事为了“复用”而“复用”把接口请求、缓存、重试、轮询全部塞进一个通用 useRequest然后每接入一个业务都要传十几个配置参数代码里全是条件分支。这种抽象最后往往只有自己看得懂别人维护成本极高。抽象是好事但每一个抽象层级都要对团队有净收益否则不如直接一点。2. 核心细节解析与实操要点2.1 封装自定义组合式函数的三层结构我沉淀下来的自定义组合式函数封装模型其实非常简单就三层参数入状态内返回值出。第一层是入参。入参尽量接收“纯数据”而非“响应式对象”同时暴露出派生数据的能力。比如 usePagination 接收初始页码和每页条数而不是接收一个ref(1)因为内部自己创建 ref 并暴露出来比去改外部状态更可控。第二层是内部状态。所有 ref、computed、watch 都定义在函数内部保证每次调用都是干净实例。内部状态如果需要外部读取暴露只读版本是更好的选择。第三层是返回值。返回值一般是一个普通对象包含状态和操作函数。状态部分尽量用只读代理保护避免外部直接修改内部状态导致不可预测的副作用。一个比较典型的封装例子分页逻辑export function usePagination(options: { page?: number; pageSize?: number } {}) { const page ref(options.page ?? 1); const pageSize ref(options.pageSize ?? 10); const total ref(0); const totalPages computed(() Math.ceil(total.value / pageSize.value)); function setPagination(nextPage: number, nextPageSize?: number) { if (nextPageSize) pageSize.value nextPageSize; page.value nextPage; } function reset() { page.value 1; total.value 0; } return { page: readonly(page), pageSize: readonly(pageSize), total: readonly(total), totalPages, setPagination, reset, }; }这个函数就是典型的“参数入、状态内、返回值出”。外部拿到的 page、pageSize 都是只读的防止有人在列表页里直接page.value 999导致翻页控件和数据不同步只能通过setPagination修改。2.2 生命周期与资源释放onScopeDispose 的正确用法组合式 API 中特别容易被忽略的一个点是资源释放。在 Options API 里我们习惯在beforeUnmount里清理定时器。组合式 API 提供了更细粒度的替代方案——onScopeDispose。onScopeDispose 的意义在于它跟组合式函数所在的作用域绑定而不只是组件绑定。这意味着你的组合式函数被用在普通组件里时组件卸载会自动触发清理如果被用在路由组件、异步组件、甚至显式创建的 effect scope 里作用域销毁时也会自动触发清理。举一个我在报表模块里真实踩过的坑。之前封了一个 useCountdown 倒计时直接在函数里setInterval却没有清理结果在几个页面复用后用户切换路由时定时器一直在跑接口请求和内存占用都异常。后来统一改成export function useCountdown(seconds: number) { const remaining ref(seconds); const timer setInterval(() { remaining.value--; if (remaining.value 0) { clearInterval(timer); } }, 1000); // 作用域销毁时兜底清理 onScopeDispose(() { clearInterval(timer); }); return { remaining }; }这样不管定时器自己有没有走到结束只要组件卸载或作用域销毁都会强制清理。所有副作用操作——定时器、事件监听、观察者、WebSocket 连接、手动创建的 watch——都应该考虑加 onScopeDispose 清理。2.3 类型安全从 ref 到泛型再到自定义类型守卫大型项目里类型安全不是加分项是底线。组合式 API 在 TypeScript 下有一个天然优势状态类型几乎可以零成本推导。ref(0)自动推导为Refnumbercomputed的返回值类型跟着计算逻辑自动走不需要手写一堆 interface。但有几个地方需要额外注意。第一接口返回的数据类型大多数时候是直接通过泛型传给组合式函数的export function useTableDataT(fetcher: (params: any) Promise{ list: T[]; total: number }) { const list refT[]([]); const loading ref(false); async function fetchList(params: any) { loading.value true; try { const data await fetcher(params); list.value data.list; return data.total; } finally { loading.value false; } } return { list, loading, fetchList }; }调用的时候传入具体的泛型参数比如useTableDataOrderItem(fetchOrders)那么list直接就推导为RefOrderItem[]模板里item.xxx有完整补全和类型检查。第二自定义类型守卫。组合式函数返回的数据经常需要判断存在性再操作。比如列表接口可能返回null需要先判空过滤。这时候写一个自定义类型守卫函数能让团队代码更清晰export function isOrderItem(item: any): item is OrderItem { return item typeof item.id number typeof item.amount number; }第三defineProps 的泛型写法。Vue 3.3 之后可以直接用泛型定义 props 类型const props defineProps{ orderId?: string; visible: boolean; }(); const emit defineEmits{ (e: close): void; (e: confirm, payload: { orderId: string }): void; }();这种写法比运行时声明更直观而且父组件传错属性名、漏传必填属性都会有编译告警。在大型团队里让编译器和 IDE 把错误挡在开发阶段远比 Code Review 时人肉查要可靠。2.4 组合式函数与 Pinia 的边界划分很多团队在引入组合式 API 之后会纠结一个问题状态到底放 Pinia 还是放组合式函数我的判断标准非常简单——跨组件共享的状态放 Pinia本组件内部职责相关的状态放组合式函数。组合式函数适合“同一个页面内多个子模块之间的逻辑复用”。比如一个弹窗组件内部用到的表单状态、校验逻辑、提交逻辑这些都不需要跨组件共享放在组合式函数里最合适。Pinia 适合“跨组件、跨页面共享的全局状态”。比如用户信息、权限点集合、主题配置、购物车数据。因为这些状态需要被多个不相干的组件读取和修改单一数据源非常重要。组合式函数和 Pinia 不是互斥关系它们常常配合使用。一种常见的模式是组合式函数读取 store 的状态但不修改 store 的状态。比如export function usePermission() { const userStore useUserStore(); const canEdit computed(() userStore.permissions.includes(order:edit)); const canExport computed(() userStore.permissions.includes(order:export)); return { canEdit, canExport }; }这里有个很容易踩的坑不要在组合式函数里把 store 的状态复制到局部 ref 再读取。// 错误示范复制后失去响应式 const userName ref(userStore.name);复制之后store 里的name变了局部userName不会跟着变界面上就出现数据不同步的诡异 bug。正确做法是直接用 computed 包一层const userName computed(() userStore.name);记住这条边界能少踩很多坑。3. 实操过程与核心环节实现3.1 场景设定订单列表页的痛点假设现在要做一个订单列表页需求大概是支持按订单号、状态、时间范围筛选分页展示有 loading 状态支持导出当前筛选条件下的数据页面上还有一个“今日成交额”卡片。这几乎是中后台系统最常见的页面类型。如果用 Options API 硬写大概会有一个 400 到 500 行的组件data 里十几个字段methods 里十几个函数watch 里监听筛选条件变化去重新请求。任何新人接手光理清数据流就需要大半天。组合式 API 的做法是把页面按业务能力拆成几个独立模块usePagination分页状态管理useSearchForm搜索表单默认值、重置、查询触发useTableData表格数据加载、loading、错误处理useSummaryCard今日成交额卡片数据这四块逻辑相互独立又通过编排层组合到一起。3.2 从组件内逻辑到 useOrderList 的完整抽取过程先看不拆的情况setup 里可能是这样const page ref(1); const pageSize ref(10); const total ref(0); const tableData refOrderItem[]([]); const loading ref(false); const searchParams reactive({ keyword: , status: undefined, dateRange: [] }); async function fetchList() { loading.value true; try { const res await fetchOrderList({ page: page.value, pageSize: pageSize.value, ...searchParams, }); tableData.value res.list; total.value res.total; } finally { loading.value false; } } function handleSearch() { page.value 1; fetchList(); }这已经是一个相对克制的写法但还是把分页、搜索、请求全都搅在一起。当页面再加入导出、今日成交额、表格列设置等功能时这个函数体就会继续膨胀。现在开始拆。第一步先把分页逻辑抽成 usePagination上面已经给出。第二步抽搜索表单逻辑export function useSearchFormT extends Recordstring, any(defaults: T) { const form reactiveT({ ...defaults }); function reset() { Object.keys(defaults).forEach((key) { form[key as keyof T] defaults[key]; }); } return { form, reset }; }第三步抽表格数据请求逻辑把请求函数作为入参export function useTableDataT(fetcher: (params: any) Promise{ list: T[]; total: number }) { const list refT[]([]); const total ref(0); const loading ref(false); async function load(params: any) { loading.value true; try { const data await fetcher(params); list.value data.list; total.value data.total; } finally { loading.value false; } } return { list, total, loading, load }; }最后在组件里做编排export function useOrderList() { const { page, pageSize, totalPages, setPagination, reset: resetPagination } usePagination(); const { form, reset: resetSearchForm } useSearchFormOrderSearchParams({ keyword: , status: undefined, dateRange: [], }); const { list, total, loading, load } useTableDataOrderItem(fetchOrderList); async function fetchList() { await load({ page: page.value, pageSize: pageSize.value, ...form, }); } function handleSearch() { resetPagination(); fetchList(); } function handleReset() { resetSearchForm(); resetPagination(); fetchList(); } return { list: readonly(list), total: readonly(total), loading: readonly(loading), form, page, pageSize, fetchList, handleSearch, handleReset, }; }这些函数拆完之后组件 setup 部分只剩下一行const orderList useOrderList();页面模板里使用orderList.list、orderList.loading、orderList.form逻辑全部收拢到一个编排层里。以后如果再加入“导出”功能只需要扩展 useOrderList 内部组件模板和组件逻辑都不需要大动。3.3 复用场景两个页面共用同一组合式函数的参数化设计订单列表页做完之后产品提了一个新需求做一个退款列表页筛选字段和交互几乎一样只是接口换了、表格列的展示不一样了。这时候上面的 useOrderList 就不能直接复用因为它内部把fetchOrderList硬编码进去了。这就是组合式函数设计时的另一个关键点凡是变化点都应该作为入参暴露。稍微改造一下把请求函数作为参数传进去export function useOrderList(fetcher: (params: any) Promise{ list: OrderItem[]; total: number }) { // ...与之前相同的逻辑只是调用 fetcher 而不是 fetchOrderList return { ... }; } // 订单页 const orderList useOrderList(fetchOrderList); // 退款页 const refundList useOrderList(fetchRefundOrderList);两个页面共用同一套分页、搜索、loading、刷新逻辑上面的差异点只集中在请求函数和表单项配置。这才体现组合式函数真正的复用价值——把不可变逻辑收进内部把可变点暴露为参数。再进一步如果两个页面的搜索表单字段不同可以把 defaults 也作为参数传进去。不要让组合式函数内部try到太多业务字段否则它就退化成只属于某个页面的私有函数了。3.4 与现有团队规范的衔接目录结构、命名规范、Code Review 清单组合式 API 最佳实践要落地光靠个人自觉不够必须有团队规范托底。我整理了我们团队现在正在用的几套规范直接分享出来。目录结构方面我们采用“通用组合式函数和业务组合式函数分层”的方式src/ composables/ usePagination.ts useSearchForm.ts useTableData.ts useDebounce.ts useThrottle.ts features/ order/ useOrderList.ts useOrderExport.ts useOrderSummary.ts refund/ useRefundList.ts通用 composables 放跨业务复用的基础能力features 下按业务域组织每个业务域内部放自己独立的组合式函数。这样新人找代码非常快不会出现两个同名组合式函数散落在不同业务文件里的混乱。命名规范方面有三条硬性要求组合式函数一律以 use 开头驼峰命名。返回值里的状态只读的用 readonly 包裹不允许直接暴露可写 ref。布尔状态的命名统一 is、has、can 前缀比如 isLoading、hasPermission、canEdit。Code Review 清单方面我会让团队在合并代码前检查以下几点组合式函数内部是否在模块作用域创建了共享响应式状态如果有必须改到函数内部。所有 setInterval、addEventListener、WebSocket、手动 watch 是否有对应的 clearInterval、removeEventListener、close、onScopeDispose 清理返回值是否暴露了不必要的可写引用能用 readonly 包裹的一律包裹。是否在组合式函数里复制了 store 状态到局部 ref如果是改为 computed。是否有重复的 watch 监听逻辑可以并入 computed如果只是为了派生值用 computed 而不是 watch。有了这套规范之后团队新成员写的组合式代码质量明显稳定至少不会出现那种“第一天能用第三天后院起火”的代码。4. 常见问题与排查技巧实录4.1 watch 触发死循环与竞态问题组合式 API 里 watch 是绕不开的但很多人用 watch 用得过于随意。最常见的两个问题死循环和竞态。死循环的典型场景是这样的watch(page, async (newPage) { const data await fetchList({ page: newPage }); total.value data.total; page.value Math.min(page.value, Math.ceil(total.value / pageSize.value)); });监听 page然后在回调里又修改 page如果恰好修改后的值和当前值不一样就会再次触发 watch形成循环。这种问题在 Options API 里一样存在但组合式 API 中更容易出现因为大家都在 setup 里堆 watch上下文不清。我的经验是能通过显式调用解决的问题不要用 watch 解决。上面这个场景排序、筛选、翻页都是用户明确触发的行为直接在事件处理函数里调用 fetchList 就好watch 并不是必需品。watch 只适合做“状态本身变化后需要响应的副作用”比如监听某个 store 值变化后更新本地缓存。竞态问题则更隐蔽。快速切换分页时上一次请求还没返回下一次请求已经发出最后返回的可能反而是旧请求的结果导致页面数据错乱。解决办法有两种第一种是请求序号标记let requestId 0; async function fetchList(params: any) { const current requestId; loading.value true; try { const data await fetcher(params); if (current requestId) { list.value data.list; total.value data.total; } } finally { if (current requestId) { loading.value false; } } }第二种是用 AbortController 取消旧请求Vue 生态里配合 fetch 非常好用let abortController: AbortController | null null; async function fetchList(params: any) { abortController?.abort(); abortController new AbortController(); try { const data await fetcher(params, { signal: abortController.signal }); // ... } catch (e) { if (e instanceof DOMException e.name AbortError) return; throw e; } }竞态问题是中后台系统里数据错乱的常见根源组合式函数里做统一封装可以在源头杜绝。4.2 组合式函数被多实例使用时状态串扰前面讲到过模块作用域共享状态的问题这里再展开一个实战场景。我们有一个useCustomerList组合式函数最初写的时候不小心在模块顶部声明了一个const selectedIds refstring[]([])结果客户列表页和客户关联弹窗同时打开时两处选中状态完全串了。排查了很久最后发现就是模块作用域共享变量导致的。解决方案很干脆所有状态必须在函数内部创建。export function useCustomerList() { const selectedIds refstring[]([]); // ... return { selectedIds: readonly(selectedIds), ... }; }每次调用 useCustomerList 都返回独立的实例。如果两个场景需要共享选中状态那应该提升到 Pinia 里去而不是在组合式函数里“共享”。这里还有一个延伸问题如果组合式函数内部用到provide/inject或者useRouter、useStore要注意调用时机。某些组合式函数只能在 setup 上下文调用不能放在普通的事件回调里调用否则会报错或拿不到上下文。4.3 computed 与 watch 的滥用边界关于 computed 和 watch我的建议是能用 computed 解决的绝不 watch能用显式调用解决的绝不 watch。computed 是纯派生数据它没有副作用不会造成隐式的数据流跳转。比如“筛选后是否符合条件”“总页数”“当前筛选条件数量”这些都是 computed 的天然场景。watch 则适合“副作用型响应”比如接口重新请求、本地存储写入、事件上报。很多人会把 watch 用在“监听 form 变化然后更新列表”这种场景。这个用法短期没问题但长期看一旦 form 字段多、依赖复杂watch 回调里频繁触发的请求会让数据流变得难以追踪。我的习惯是查询动作只由用户的高层操作触发比如点击搜索、翻页、重置而不是由底层字段变化自动触发。这样心智负担最小。4.4 工程化实践AI 编程助手在大型代码库中的使用建议说到工程化最近团队也引进了 AI 编程助手比如 Claude Code 这类命令行工具在大型代码库里的用法很有讲究。我自己体验下来它最擅长的不是“替你写新功能”而是“重构已有代码”和“审查潜在副作用”。举一个具体例子。我们团队之前有一批手写的 Options API 组件我想把里面散落的数据请求逻辑抽成组合式函数。这种操作如果纯手工做改一个组件就要一两个小时而且容易遗漏生命周期清理。用 Claude Code 辅助时我会先给它一个非常明确的指令把组件中data中与请求相关的字段、methods中的请求方法、beforeUnmount中的清理逻辑提取到composables/useTableData.ts中保持对外接口不变。它会帮我生成初版代码我再结合上面提到的 Code Review 清单逐项检查修改效率高了一倍都不止。另外 AI 助手在“审计副作用”这块也很好用。组合式函数里最常见的 bug 就是定时器没清理、事件监听没移除。让 AI 扫描整个项目里所有使用setInterval、addEventListener、new WebSocket的代码然后把组合式函数中是否有对应清理逻辑的报告列出来这份报告基本准确率很高剩下的就是人工确认修掉。但我有一个很实在的提醒AI 生成的代码一定要过自己的心智模型不要因为 AI 生成的代码“看起来能运行”就直接合入。特别是它看似合理地创建了一个模块级共享变量、或者在某个地方悄悄引入了一个 watch这些都是组合式 API 的坑点。团队里我通常建议的做法是AI 生成初稿人做设计审查和边界审查然后单测兜底。在大型代码库中与 AI 配合最好的姿势是“把设计做好让 AI 干执行”。先把组合式函数的入参、返回值、职责边界定清楚告诉 AI 每一个函数的职责是什么然后让它去生成实现。这样既能把控架构又能享受效率红利。5. 写在最后一点实际体会玩组合式 API 这几年最大的体会是它不是一个“语法新特性”而是一套组织代码的心智模型。Options API 逼着你按代码类型组织组合式 API 逼着你按业务能力组织。后者明显更适合大型项目的长期维护。但所有好处都有一个前提团队必须建立统一规范并且把规范落到代码评审和实际开发流程里。函数该拆就拆状态该收回就收回副作用该清理就清理类型能省就省但该写就写。这些看着琐碎的东西放到一个月、三个月、半年的维度去看差距会大得惊人。最后分享一个小技巧是我最近一直在用的写组合式函数之前先在注释里写清楚 Input、Output、Side Effect 三行。任何函数只要这三行写得清楚就不太可能写出烂代码。这个习惯比任何框架特性都管用。