Vue Composition API的核心价值是用功能模块替代选项分类组织代码，通过Composable分层封装、语义化脚本顺序、状态分层管理及目录即契约实现结构清晰、职责单一、类型可溯。
Vue Composition API 的核心价值，不是多写几个 ref 或 computed，而是用“功能模块”代替“选项分类”来组织代码。结构清晰的关键，在于分层明确、职责单一、类型可溯。
按功能拆分逻辑：用 Composable 封装可复用能力
把用户管理、分页、搜索、权限校验等业务能力，各自封装成独立的 useXXX 函数，放在 src/composables/ 下。每个函数只做一件事，返回明确的状态和方法。
-
useUserList()负责拉取、缓存、刷新用户数据，不掺杂 UI 渲染或路由跳转 -
usePagination({ pageSize: 10 })管理当前页、总条数、跳页逻辑，对外暴露currentPage和goToPage -
useSearch(['name', 'email'])提供防抖输入、关键词过滤、重置功能，与具体组件解耦
组件内按语义顺序组织代码
在 <script setup lang="ts"></script> 中，严格遵循导入 → 声明（props/emits）→ 组合函数调用 → 响应式状态 → 计算属性 → 方法 → 生命周期钩子 的顺序。这样一眼就能看出组件“依赖什么、拥有什么、能做什么”。
- props 必须用 TypeScript interface 显式定义，例如
defineProps() - 事件用
defineEmits()类型化，IDE 能自动提示合法事件 - 避免在 setup 内直接写业务逻辑，全部下沉到 composable，组件只负责组合与协调
状态分层管理：局部 + 全局 + 持久化
不是所有状态都该进 Pinia。合理分层才能避免过度设计：
HISUI 前端框架开发指南（IRIS版）
下载
HISUI 前端框架基础开发指南。HISUI 是基于 easyui 二次开发的 jQuery UI 组件库，专为医疗信息系统设计。当涉及 HISUI 组件开发、jQuery easyui 表格/表单/布局/窗口、医疗系统前端页面编写时使用此 skill。 涵盖 40 个组件的官方文档参考，支持声明式与编程式两种初始化方式，提供 $cm/$m 数据访问方法。
立即学习“前端免费学习笔记（深入）”；
- 组件内部状态（如表单临时输入、模态框开关）用
ref或reactive直接管理 - 跨多个组件共享的业务状态（如当前用户信息、主题偏好）走 Pinia，配合 TypeScript 接口约束 store 结构
- 需持久化的数据（如用户筛选条件、折叠面板状态）用
localStorage+ 自定义 hook 封装，不污染业务逻辑
目录即契约：用结构表达设计意图
目录命名不是为了好看，而是让新成员打开项目就能理解架构边界：
-
src/components/：纯 UI 组件，无业务逻辑，通过 props 和 slots 接收一切外部输入 -
src/composables/：所有useXXX，每个文件导出一个函数，名称即能力描述 -
src/types/：全局接口，如User、ApiResponse，被 components 和 composables 共同引用 -
src/utils/：无副作用的工具函数（日期格式化、深克隆），不依赖 Vue API
这种结构不依赖框架黑魔法，靠的是对职责边界的清醒认知和持续的代码纪律。写起来稍慢一点，但半年后改需求时，你会感谢当初没把搜索逻辑塞进用户列表组件里。
