vben-admin

Vben Admin 5.x 前端开发规范

本规范用于指导基于 Vben Admin 5.x 的前端开发，当创建页面、组件、API 接口或前端功能时自动使用。

一、技术栈

项目使用 Vben Admin 5.x (Ant Design Vue) + TypeScript + Vite 技术栈，具体版本与用途如下：

• Vue 3.5.x：UI 框架
• TypeScript 5.x：类型系统
• Ant Design Vue 4.x：组件库
• Vite 7.x：构建工具
• Pinia 3.x：状态管理
• Vue Router 4.x：路由
• Axios：HTTP 客户端

二、目录结构

前端源码目录为 frontend/apps/web-antd/src/，结构约定如下：

• api/：API 接口，按模块组织，如 api/{module}/index.ts
• views/：页面视图，按模块组织，包含 index.vue（列表页）、detail.vue（详情页）、form.vue（表单页）
• components/：公共组件
• stores/：状态管理，如 stores/{module}.ts
• router/：路由配置，位于 router/routes/{module}.ts
• hooks/：自定义 Hooks
• utils/：工具函数
• types/：类型定义，如 types/{module}.ts

三、代码模板

1. API 接口（api/{module}/index.ts）：从 @vben/request 引入 defHttp，从 @/types/{module} 引入实体、列表参数与表单数据类型；通过 enum Api 定义 List、Detail、Create、Update、Delete 等接口路径；导出 get{EntityName}List、get{EntityName}Detail、create{EntityName}、update{EntityName}、delete{EntityName} 方法，分别使用 defHttp.get/post/put/delete 调用，并带中文注释。

2. 类型定义（types/{module}.ts）：定义 {EntityName} 实体接口（id、name、createdAt、updatedAt 等字段）、{EntityName}ListParams 列表查询参数（page、size、keyword）与 {EntityName}FormData 表单数据接口（name）。

3. 列表页（views/{module}/index.vue）：使用 Page、PageHeader、Card、Form、Input、Table、Button、Popconfirm、Space 等组件；包含搜索区域（关键词查询与重置）、操作区域（新增按钮）、表格（列配置、加载状态、分页、操作列含编辑与删除）；脚本使用 script setup lang=ts，定义 searchForm、loading、dataSource、pagination、columns，实现 loadData、handleSearch、handleReset、handleTableChange、handleCreate、handleEdit、handleDelete，并在 onMounted 时加载数据；使用 defineOptions 声明组件名。

4. 表单页（views/{module}/form.vue）：使用 Page、PageHeader、Card、Form、FormItem、Input、Button、Space 等组件；根据路由参数判断新增或编辑模式；包含名称字段与校验规则（必填）、提交与取消按钮；脚本实现 loadDetail（编辑时加载详情）、handleSubmit（校验后按编辑/新增调用对应 API 并提示）、handleBack 返回列表，使用 submitting 控制提交状态。

5. 路由配置（router/routes/{module}.ts）：定义 RouteRecordRaw 数组，父路由 path 为 /{module}，带 title 与 icon 元信息；子路由包含列表页（默认 path，组件指向 views/{module}/index.vue）与表单页（path 为 form/:id?，hideMenu 为 true）。

四、命名规范

• 文件夹：kebab-case，示例 user-management/
• 组件文件：PascalCase.vue，示例 UserList.vue
• 工具文件：camelCase.ts，示例 formatDate.ts
• 类型文件：camelCase.ts，示例 user.ts
• 组件名：PascalCase，示例 UserList
• 变量名：camelCase，示例 userName
• 常量名：UPPER_SNAKE，示例 MAX_PAGE_SIZE
• 事件名：handle + 动作，示例 handleSubmit

五、最佳实践

• TypeScript：所有文件使用 TypeScript，定义完整类型
• 组合式 API：使用 <script setup lang="ts">
• 中文注释：所有函数、变量添加中文注释
• API 封装：统一使用 defHttp 封装请求
• 类型定义：接口数据类型放在 types/ 目录
• 组件命名：使用 defineOptions({ name: 'XxxComponent' })

六、适用项目

文档中提到的示例项目为应急管理系统（yingjiguanli），技术栈为 Vben Admin 5.x + Vue 3 + TypeScript。

七、限制与缺失信息

资料未提供许可证、安装命令、依赖安装步骤、后端接口约定、构建部署方式、浏览器兼容范围、测试方案以及价格或收费模式等信息，暂未提供。