Vue setup 函数如何在大型项目中保持代码结构的清晰统一

大型Vue3项目中setup函数的关键在于组织方式，应按业务能力划分组合函数、统一命名规范、明确输入输出、标准化响应式声明及setup内部结构顺序，并通过ESLint、目录约束和CI流程保障落地。

在大型 Vue3 项目中，setup 函数本身不是负担，关键在于组织方式。它不强制你把所有逻辑塞进一个函数里，而是提供了一套可拆、可复、可追踪的结构基础。清晰统一的核心，是把“功能边界”变成代码边界，而不是靠注释或命名约定来维系。

按业务能力划分组合函数（useXxx）

把关联的状态、方法、副作用封装成独立的组合函数，每个函数只负责一个明确的能力域。比如用户管理页不需要知道订单分页怎么请求，只需要调用 useUserList() 和 useOrderList()。

1. 命名统一：全部以 use 开头，如 useAuth、useFormValidate、useTablePagination
2. 输入聚焦：只接收必要参数（如 API 路径、初始筛选条件），不传整个 props 或 context
3. 输出明确：返回解构友好的对象，含响应式数据 + 操作函数 + 状态标记（如 data、loading、fetch）

统一状态声明与响应式处理规范

避免混用 ref 和 reactive 导致理解成本上升。团队需约定：

1. 单个基础值（数字、字符串、布尔）用 ref，如 const searchKeyword = ref('')
2. 结构化对象（表单、API 响应体、配置项）用 reactive，如 const formData = reactive({ name: '', email: '' })
3. 禁止直接在 setup 中写裸变量（如 let count = 0），所有需要响应式的都必须显式声明

标准化 setup 内部结构顺序

每个组件的 setup 函数保持固定阅读流，降低新成员上手成本：

1. 先解构 props 和 context（如 emit、slots）
2. 再调用组合函数，按功能重要性或页面区域从上到下排列（如 useHeader → useMainTable → useSidePanel）
3. 接着定义仅本组件使用的局部逻辑（如某个按钮的特殊弹窗控制）
4. 最后统一 return，按“数据 → 方法 → 其他”分组，用空行隔开

配套工程约束保障落地

光靠自觉难维持长期统一，需工具链辅助：

1. ESLint 插件（如 @vue/eslint-config-typescript + 自定义规则）检查 ref/reactive 使用是否合规
2. 目录结构强制分层：composables/useXxx.ts 存组合函数，components/xxx/index.vue 只负责组装和模板
3. CI 流程中校验 setup 函数长度（建议不超过 80 行），超长则提示需拆分为组合函数