# 前端应用代码规范（工程执行版） > 适用栈：React / Vue / Svelte / 原生组件化 Web / 小程序等前端应用。语言、HTML、CSS 细则仍需同时遵守对应规范。 ## 1. 页面组件约束（强制） - 单页单组件：一个路由页面只允许一个页面组件文件，例如 `UserListPage.tsx`、`OrderDetail.vue`。 - 页面组件只做汇聚：只允许组织布局、引入业务组件、连接页面级 Hook / Composable，不直接承载业务规则。 - 页面组件不得直接写接口请求、复杂数据转换、表单校验规则、权限判断、定时器、事件总线订阅等业务逻辑。 - 页面组件的分支只允许用于页面级骨架切换，例如 loading / empty / error / ready；超过 3 个业务分支时必须下沉到组件或 Hook。 - 页面组件建议不超过 120 行，超过 180 行必须拆分业务组件或页面 Hook。 ## 2. 目录与职责 - `pages/`：路由入口与页面组件，只做组件汇聚和页面级状态接线。 - `features/`：按业务域组织组件、Hook / Composable、状态、接口适配与类型。 - `components/`：跨业务复用的展示组件，不依赖具体业务接口。 - `hooks/` / `composables/`：封装业务流程、请求状态、事件订阅、副作用与可复用交互逻辑。 - `services/` / `api/`：统一 API client、请求参数、响应 DTO、错误码映射。 - `stores/`：全局状态，仅存放跨页面共享且有明确生命周期的数据。 ## 3. 组件分层 - 页面组件负责“摆放什么”，业务组件负责“如何交互”，Hook / Composable 负责“状态与副作用如何流转”。 - 展示组件只通过 props / events / slots 接收数据和回调，不直接访问路由、全局 store 或 API。 - 业务组件可以组合展示组件和业务 Hook，但不得把同一业务流程复制到多个组件。 - 弹窗、抽屉、表格、表单等复杂区域应独立为业务组件，页面组件只传入必要上下文。 - 跨组件共享逻辑必须抽成 Hook / Composable 或领域工具函数，禁止复制粘贴。 ## 4. Hook / Composable 规则 - Hook / Composable 命名必须体现业务意图，例如 `useUserListQuery`、`useOrderSubmitForm`。 - 外部输入必须显式声明并校验边界：路由参数、查询条件、表单初值、权限上下文。 - 返回值应稳定且可读，至少区分 `data`、`status` / `loading`、`error`、`actions`。 - 副作用必须可清理：事件监听、定时器、订阅、请求取消在组件卸载时释放。 - 禁止在 Hook / Composable 中直接操作不相关 DOM；确需操作时说明原因并限制作用域。 - 单个 Hook / Composable 建议只覆盖一个业务流程，出现多个独立流程时拆分。 ## 5. API 与数据流 - 禁止在页面组件或展示组件中散落 `fetch` / `axios` / SDK 调用。 - 请求统一进入 `services/` / `api/` 层，完成路径、方法、参数、响应 DTO 与错误码归一。 - 服务端字段进入 UI 前必须经过显式映射，避免把后端 DTO 直接扩散到组件树。 - 列表查询必须约束分页、排序、过滤默认值，并避免无限制拉取。 - 提交类操作必须处理重复提交、成功反馈、失败回填与必要的乐观更新回滚。 - 跨页面共享数据优先使用服务端缓存库或全局 store，局部页面状态不提升为全局状态。 ## 6. 表单、路由与权限 - 表单校验规则集中维护在 Hook / Composable 或 schema 文件，错误提示必须定位到字段。 - 表单提交逻辑不得写在页面组件中；页面组件只传入上下文并汇聚表单组件。 - 路由参数必须在进入业务逻辑前校验，非法参数进入 404 / 错误页或明确错误态。 - 权限判断必须集中封装，页面组件只选择汇聚有权限视图、无权限视图或跳转逻辑。 - 需要保护的路由必须有路由守卫或等价机制，元素级隐显不能替代接口鉴权。 ## 7. UI、样式与可访问性 - 样式优先使用项目统一方案：CSS Modules、Scoped CSS、Tailwind、BEM 或设计系统，不混用多套命名体系。 - 颜色、字号、间距、圆角、阴影、层级使用设计 token 或主题变量，不在组件内散落硬编码。 - 响应式布局必须覆盖目标移动端与桌面断点，关键区域不得横向溢出或互相遮挡。 - 交互元素优先使用语义标签，键盘可达，表单控件有 label，图片有有效 alt。 - 弹窗、抽屉、下拉等浮层必须处理焦点、关闭行为、层级与滚动锁定。 ## 8. 性能、安全与测试 - 路由级页面和重型组件应懒加载，首屏不加载无关业务模块。 - 大列表必须使用分页、虚拟滚动或增量加载，禁止一次性渲染不可控数据量。 - 用户可控内容默认转义；使用富文本或 HTML 注入能力时必须经过可信白名单清洗。 - token、密钥、个人敏感信息不得硬编码或明文长期存储在前端持久化介质。 - 新增页面至少覆盖页面 Hook / Composable 的成功路径与失败路径测试。 - 关键用户流程建议补充组件测试或 E2E：加载、空态、错误态、提交成功、提交失败。