frontend

最近更新: 2025-09-18

Frontend Engineering Baseline

1. 范围与定位

• 本文件提供框架无关的前端工程基线（目录、质量、可观测、部署等）。
• 具体框架专项规范：Vue → vue.mdc（本仓库提供）；React / Svelte 可另行补充。

2. 目录结构（通用示例）

src/
  main.ts          # 入口
  app/             # 应用入口/根组件（按框架）
  router/          # 路由定义与守卫（按框架）
  pages/           # 路由页面 (视图容器)
  components/      # 可复用基础组件（无业务）
  features/        # 业务特性模块（聚合页面/组件/逻辑）
  state/           # 状态模块（Pinia/Redux/Zustand 等）
  composables/     # 复用逻辑（hooks/useXXX）
  api/             # API / SDK / 网关调用封装
  directives/      # 自定义指令
  plugins/         # Vue / 第三方插件注册
  tokens/          # 设计系统 Token（JSON / TS / CSS Vars）
  styles/          # 全局样式入口 & 预处理（Tailwind / SCSS / PostCSS）
  assets/          # 静态资源 (图标/字体/图片)
  utils/           # 纯函数工具，不含框架耦合
  tests/           # 测试配置或全局 setup

可选：env.d.ts (类型 shim)、mocks/ (MSW 本地 API Mock)、prototypes/ (实验性验证)。 Vue 专属实践：详见 vue.mdc（TypeScript/状态/接口错误处理/设计系统 Token 等）。

3. 状态管理原则（通用）

• 优先局部：先本地组件 / composable，后 Pinia store，最后跨域全局单例。
• Store 颗粒度：按业务垂直切分（auth/user/order），禁止“core/global”巨无霸。
• 远程数据：优先 TanStack Query（失效策略、缓存键、重试、并发去重）。
• Store 中避免直接异步副作用：放入 action 或 composable；保持可测试性。
• 仅当多个组件需要订阅同一响应式源且生命周期独立时引入 store。
• 避免“缓存即状态”混乱：服务端数据缓存交 Query；本地持久偏配置信息交 store。

4. 组件/视图设计（通用）

• 分类：Base（原子 UI，无业务） / Presentational（布局组合） / Feature（绑定具体业务） / Page（路由承载）。
• Props 精简 & 明确类型；禁止传递整块 store 或巨大对象（用解构 + 明确字段）。
• 交互拓展：优先使用 slots / scoped slots；跨层级依赖用 provide/inject 或 composable 而非深层 prop drilling。
• 避免多布尔 props 组合爆炸：改用枚举 variant / mode。
• 复用逻辑抽取 composable（useXxx）；UI + 逻辑分离（.vue 内轻逻辑）。
• 第三方组件二次封装：隔离设计系统 Token / 主题适配，避免全局直接耦合。
• 提供稳定测试选择器：data-test="component-name"。

5. TypeScript 规范（通用）

• 禁止 any（例外需 // eslint-disable-next-line @typescript-eslint/no-explicit-any + 原因）。
• interface vs type：稳定结构接口；条件/联合/映射优先 type。
• 将 API DTO 放在 api/types.ts 或分组；生成型 (OpenAPI) 代码与手写类型分隔。
• 区分 Domain Model vs View Model：转换层明确命名（mapUserDtoToModel）。
• 适度使用 defineProps, defineEmits 辅助推断；复杂组件抽出 Props 类型单独导出。
• 避免滥用 as 断言；优先类型收窄（类型守卫、判空）。
• 运行时校验（Zod）补充 TS 静态不可信输入。