12.7 前端编码规范

概述

前端规范汇总：三件套对齐、组件使用、权限、状态管理、类型与样式。配套工具链：ESLint + Prettier + Stylelint + vue-tsc + commitlint。

三件套与契约（最高优先级）

□ api url 对齐 gmeta path（无 /api 前缀重复、无 /v1）
□ querySchemas field ↔ PageReq json ↔ LikeFields/EqFields（三件同步）
□ columns prop ↔ Item/DetailRes json
□ edit 表单 ↔ AddReq/UpdateReq（全量提交语义）
□ 按钮 v-permission ↔ gmeta permission（复制粘贴防拼错）
□ 枚举列展示 {field}Text（不硬编码文案）
□ 登录读 data.access_token（下划线）

组件使用

□ 列表用 Page 容器 + Table(columns 配置) + pagination
□ 复杂列用 render 函数（h + Element Plus 组件）
□ 筛选用 querySchemas 配置（勿手写搜索区）
□ 下拉选项优先字典驱动（getDictItemList）
□ 上传用 Upload 组件（持 URL，后端转正）
□ 图片展示用后端已补域名字段（GetFileUrl）
□ 弹窗用 Modal 封装；确认删除用 ElMessageBox

状态与逻辑

□ 状态走 Pinia store（token/用户/路由/标签页）；勿全局变量
□ 本地存储统一 storage 封装 + mutation-types 常量
□ HTTP 统一 http.request（勿绕过封装裸 axios）
□ 公共逻辑抽 hooks/；工具函数进 utils/
□ 类型：接口出入参定义类型；跑通 pnpm type:check

样式

□ scoped 样式；颜色用 Element CSS 变量（随主题）
□ 布局用栅格组件；少 deep 覆盖
□ 样式改动过 stylelint

质量门禁

pnpm type:check      # vue-tsc
pnpm lint:eslint     # ESLint
pnpm lint:prettier   # 格式化
pnpm lint:stylelint  # 样式
pnpm build           # 构建验证

反例速查

❌ 直接 axios.get('/api/user/page')          绕封装 + url 重复 /api
❌ options: [{label:'正常',value:1}] 硬编码    应字典驱动
❌ status 直接展示（显示 1/2）                 应展示 statusText
❌ 按钮无 v-permission                       权限裸奔（UX 层缺失）
❌ 每次请求重新登录拿 token                    用 refresh 轮换
❌ 组件内大量业务逻辑                          抽 hooks/store
❌ 直接 localStorage.setItem('token')          统一 storage + 常量
❌ 页面硬编码颜色 #1890ff                      用 var(--el-color-primary)
❌ 布尔/枚举用魔法数字散落                      用 enums 常量

Review 检查项

□ 新页面走三件套结构（index/edit/detail/columns/querySchemas）
□ 接口函数 JSDoc 注释（生成器同款风格）
□ 列表空态/加载态/错误态处理
□ 表单校验（前端提示 + 对齐后端 v 标签）
□ 删除/危险操作二次确认
□ 权限变更后按钮正确显隐（超管/普通角色双测）
□ type:check 与 build 通过