Vue3 全栈应用架构：组合式 API 不是把逻辑随便抽走
Vue3 全栈应用架构：组合式 API 不是把逻辑随便抽走
一、组合式 API 的价值是组织复杂度
Vue3 的组合式 API 给了前端更灵活的逻辑复用方式，但它不是把任何代码都抽成useXxx。全栈应用变复杂后，状态、请求、权限、表单和缓存都会交织在一起。组合式 API 的价值，是把相关逻辑按业务语义组织起来，而不是制造一堆难以追踪的工具函数。
一个常见误区，是把组件里的所有变量和方法都搬进 composable。结果组件看起来短了，真实逻辑却分散到多个文件，调试更困难。好的 composable 应该有明确职责，例如管理分页查询、处理表单提交、封装权限判断、同步 URL 状态。职责不清的抽象，只是换了位置的复杂度。
二、架构分层：页面、业务组合函数和基础请求
flowchart TD A[Page Component] --> B[Business Composable] B --> C[API Client] B --> D[State Store] C --> E[Backend Service] A --> F[UI Components]页面组件负责布局和组合，业务 composable 负责业务状态和流程，API client 负责请求细节，UI 组件保持无业务依赖。这样页面不会变成大杂烩，基础组件也不会偷偷知道业务接口。边界清楚后，测试和迁移都更容易。
三、组合函数示例：把请求状态表达完整
下面是一个简化的分页查询 composable。重点是状态完整，而不是代码最短。
import { ref } from "vue"; export function usePagedQuery<T>(loader: (page: number) => Promise<T[]>) { const page = ref(1); const items = ref<T[]>([]); const loading = ref(false); const error = ref<string | null>(null); async function load() { loading.value = true; error.value = null; try { items.value = await loader(page.value); } catch (err) { error.value = err instanceof Error ? err.message : "unknown error"; } finally { loading.value = false; } } return { page, items, loading, error, load }; }这个函数没有绑定具体业务，但表达了分页查询的通用状态。调用方可以决定 loader 来自哪个接口。若未来加入缓存、重试或取消请求，也能集中处理。组合式 API 的优势在于让逻辑边界更清楚，而不是把组件拆碎。
四、全栈协同：前端状态要匹配后端语义
全栈应用里，前端状态设计不能脱离后端语义。比如订单状态、任务状态、支付状态都应来自后端状态机，而不是前端自己拼字符串。前端可以做展示映射，但不能创造业务事实。否则后端变更后，前端状态很容易出现不一致。
错误处理也要统一。后端应返回稳定错误码，前端根据错误码展示文案和操作。不要在每个组件里解析不同错误文本。全栈项目的小而美，不是少写类型，而是让契约简单稳定。TypeScript 类型、OpenAPI 或 GraphQL schema 都可以成为前后端契约。
最后，避免过度全局状态。Vue 项目很容易把 Pinia 当成万能仓库。服务器状态可以交给查询缓存或页面级状态，局部交互留在组件内，真正跨页面共享的才进入全局 store。状态越靠近使用位置，维护成本越低。
生产落地补充：从能跑到可维护
从生产落地角度看，这类方案不能只停留在主流程。更关键的是把输入校验、失败分支、资源上限和回滚路径提前写清楚。主流程通常容易在演示环境里跑通，真正暴露问题的是异常输入、依赖抖动、并发放大和权限边界。一篇技术方案如果没有解释这些约束，读者很难判断它能否放进真实系统。
评估时建议先定义三类指标：正确性指标、稳定性指标和成本指标。正确性指标回答结果是否可信，稳定性指标回答失败时是否可控，成本指标回答持续运行是否划算。三类指标要同时进入验收清单，不能只用平均耗时或单次成功率证明方案有效。
实现层面还需要把观测数据留出来。日志至少包含请求标识、关键参数摘要、耗时、状态和错误类型；指标至少覆盖成功率、超时率、重试次数和队列长度；必要时再补 Trace 关联上下游调用。这样排查问题时不用靠猜，也能区分是代码逻辑、外部依赖还是容量配置导致的故障。
五、总结
Vue3 全栈应用应把组合式 API 用于组织业务逻辑，而不是盲目抽函数。页面、composable、API client、状态和后端契约边界清楚，才能让全栈应用保持简洁和可维护。