Duke Admin 前端开发手册
目录
项目概述
Duke Admin 前端是基于 Vue 3 + TypeScript + Vite 构建的现代化后台管理系统前端项目。采用组件化开发模式,支持响应式布局,提供丰富的管理功能。
主要特性
- 🚀 基于 Vue 3 + TypeScript + Vite
- 🎨 使用 Element Plus UI 组件库
- 📦 状态管理使用 Pinia
- 🛣️ 路由管理使用 Vue Router 4
- 🔐 集成 JWT 认证
- 📊 集成 ECharts 图表库
- 🎯 支持 SSE (Server-Sent Events)
- 📱 响应式设计
技术栈
核心框架
- Vue 3.3.4 - 渐进式 JavaScript 框架
- TypeScript 5.1.3 - JavaScript 的超集,提供类型检查
- Vite 4.4.7 - 下一代前端构建工具
UI 组件库
- Element Plus 2.3.8 - 基于 Vue 3 的组件库
- @element-plus/icons-vue 2.1.0 - Element Plus 图标库
- @ant-design/icons-vue 7.0.1 - Ant Design 图标库
状态管理
- Pinia 2.1.4 - Vue 的状态管理库
路由管理
- Vue Router 4.2.4 - Vue.js 官方路由管理器
HTTP 客户端
- Axios 1.4.0 - 基于 Promise 的 HTTP 客户端
工具库
- @vueuse/core 13.2.0 - Vue 组合式 API 工具集
- @vueuse/head 2.0.0 - Vue 3 的 head 管理
- crypto-js 4.2.0 - 加密库
- nprogress 0.2.0 - 进度条库
图表库
- ECharts 5.6.0 - 数据可视化图表库
开发工具
- Sass 1.64.1 - CSS 预处理器
- vue-tsc 2.2.10 - Vue TypeScript 编译器
项目结构
duke-vue/
├── public/ # 静态资源目录
├── src/ # 源代码目录
│ ├── api/ # API 接口定义
│ │ ├── AuthApi.ts # 认证相关接口
│ │ ├── UserApi.ts # 用户管理接口
│ │ ├── RoleApi.ts # 角色管理接口
│ │ ├── MenuApi.ts # 菜单管理接口
│ │ ├── DeptApi.ts # 部门管理接口
│ │ ├── PostApi.ts # 岗位管理接口
│ │ ├── DictApi.ts # 字典管理接口
│ │ ├── NoticeApi.ts # 通知公告接口
│ │ ├── OperLogApi.ts # 操作日志接口
│ │ ├── LoginLogApi.ts # 登录日志接口
│ │ ├── NotificationApi.ts # 通知接口
│ │ └── monitor/ # 监控相关接口
│ ├── assets/ # 静态资源
│ ├── components/ # 公共组件
│ │ ├── Editor/ # 富文本编辑器
│ │ ├── DictTag/ # 字典标签组件
│ │ ├── SvgIcon/ # SVG 图标组件
│ │ ├── Pagination/ # 分页组件
│ │ ├── icons/ # 图标组件
│ │ └── SSEStatus.vue # SSE 状态组件
│ ├── layout/ # 布局组件
│ ├── model/ # 数据模型
│ ├── router/ # 路由配置
│ ├── store/ # 状态管理
│ ├── styles/ # 样式文件
│ ├── utils/ # 工具函数
│ ├── views/ # 页面组件
│ │ ├── dashboard/ # 仪表板页面
│ │ ├── error-page/ # 错误页面
│ │ ├── home/ # 首页
│ │ ├── login/ # 登录页面
│ │ ├── monitor/ # 监控页面
│ │ ├── redirect/ # 重定向页面
│ │ ├── system/ # 系统管理页面
│ │ ├── test/ # 测试页面
│ │ └── tool/ # 工具页面
│ ├── App.vue # 根组件
│ ├── main.ts # 应用入口
│ ├── style.css # 全局样式
│ └── vite-env.d.ts # Vite 环境类型
├── .env.development # 开发环境配置
├── .env.production # 生产环境配置
├── index.html # HTML 模板
├── package.json # 项目依赖
├── tsconfig.json # TypeScript 配置
├── vite.config.ts # Vite 配置
└── README.md # 项目说明
开发环境搭建
环境要求
- Node.js >= 16
- npm >= 8
安装步骤
- 克隆项目
git clone <repository-url>
cd duke-vue
- 安装依赖
npm install
- 启动开发服务器
npm run dev
- 构建生产版本
npm run build
- 预览生产版本
npm run preview
环境配置
开发环境配置 (.env.development)
# API 基础路径
VITE_APP_BASE_API=/api
# 应用标题
VITE_APP_TITLE=Duke Admin
生产环境配置 (.env.production)
# API 基础路径
VITE_APP_BASE_API=/api
# 应用标题
VITE_APP_TITLE=Duke Admin
核心模块详解
1. API 接口模块 (src/api/)
API 接口模块采用 TypeScript 定义,提供类型安全的接口调用。
接口定义规范
// 示例:用户管理接口
export interface UserQuery {
pageNum: number;
pageSize: number;
userName?: string;
status?: string;
}
export interface UserInfo {
userId: number;
userName: string;
nickName: string;
email: string;
status: string;
createTime: string;
}
export const UserApi = {
// 获取用户列表
getUserList: (params: UserQuery) =>
request.get<PageResult<UserInfo>>("/system/user/list", { params }),
// 获取用户详情
getUserInfo: (userId: number) =>
request.get<UserInfo>(`/system/user/${userId}`),
// 新增用户
addUser: (data: Partial<UserInfo>) => request.post("/system/user", data),
// 更新用户
updateUser: (data: Partial<UserInfo>) => request.put("/system/user", data),
// 删除用户
deleteUser: (userIds: number[]) =>
request.delete("/system/user/" + userIds.join(",")),
};
2. 组件模块 (src/components/)
公共组件
- Editor: 富文本编辑器组件
- DictTag: 字典标签组件,用于显示字典值
- SvgIcon: SVG 图标组件
- Pagination: 分页组件
- SSEStatus: SSE 连接状态组件
组件使用示例
<template>
<div>
<!-- 字典标签 -->
<DictTag :options="dict.type" :value="scope.row.status" />
<!-- SVG 图标 -->
<SvgIcon icon-class="user" />
<!-- 分页 -->
<Pagination
v-model:page="queryParams.pageNum"
v-model:limit="queryParams.pageSize"
:total="total"
@pagination="getList"
/>
</div>
</template>
3. 路由模块 (src/router/)
路由配置采用 Vue Router 4,支持动态路由和权限控制。
路由配置示例
import { createRouter, createWebHistory } from "vue-router";
const routes = [
{
path: "/login",
name: "Login",
component: () => import("@/views/login/index.vue"),
meta: { title: "登录" },
},
{
path: "/",
component: Layout,
redirect: "/dashboard",
children: [
{
path: "dashboard",
name: "Dashboard",
component: () => import("@/views/dashboard/index.vue"),
meta: { title: "仪表板", icon: "dashboard" },
},
],
},
];
const router = createRouter({
history: createWebHistory(),
routes,
});
4. 状态管理模块 (src/store/)
使用 Pinia 进行状态管理,提供响应式的状态存储。
Store 定义示例
import { defineStore } from "pinia";
export const useUserStore = defineStore("user", {
state: () => ({
token: "",
userInfo: null,
roles: [],
permissions: [],
}),
getters: {
isLoggedIn: (state) => !!state.token,
hasPermission: (state) => (permission: string) =>
state.permissions.includes(permission),
},
actions: {
setToken(token: string) {
this.token = token;
},
setUserInfo(userInfo: any) {
this.userInfo = userInfo;
},
logout() {
this.token = "";
this.userInfo = null;
this.roles = [];
this.permissions = [];
},
},
});
5. 工具函数模块 (src/utils/)
提供常用的工具函数,包括请求封装、权限验证、数据格式化等。
主要工具函数
- request.ts: Axios 请求封装
- auth.ts: 认证相关工具
- validate.ts: 数据验证工具
- index.ts: 通用工具函数
开发规范
1. 代码规范
TypeScript 规范
- 使用 TypeScript 严格模式
- 为所有函数参数和返回值定义类型
- 使用接口定义数据结构
- 避免使用
any类型
Vue 组件规范
- 使用 Composition API
- 组件名使用 PascalCase
- Props 定义使用 TypeScript 接口
- 事件名使用 kebab-case
文件命名规范
- 组件文件使用 PascalCase
- 工具文件使用 camelCase
- 常量文件使用 UPPER_SNAKE_CASE
- 类型定义文件使用 .d.ts 后缀
2. 目录结构规范
views/
├── module/ # 模块目录
│ ├── index.vue # 模块主页面
│ ├── components/ # 模块私有组件
│ ├── api/ # 模块 API
│ └── types/ # 模块类型定义
3. 组件开发规范
组件结构
<template>
<!-- 模板内容 -->
</template>
<script setup lang="ts">
// 导入
import { ref, onMounted } from "vue";
import type { ComponentProps } from "./types";
// Props 定义
interface Props {
title: string;
data: any[];
}
const props = withDefaults(defineProps<Props>(), {
title: "",
data: () => [],
});
// Emits 定义
const emit = defineEmits<{
change: [value: string];
submit: [data: any];
}>();
// 响应式数据
const loading = ref(false);
// 方法
const handleSubmit = () => {
emit("submit", props.data);
};
// 生命周期
onMounted(() => {
// 初始化逻辑
});
</script>
<style scoped>
/* 样式 */
</style>
4. API 开发规范
接口定义
// 请求参数接口
export interface QueryParams {
pageNum: number;
pageSize: number;
keyword?: string;
}
// 响应数据接口
export interface ResponseData<T> {
code: number;
message: string;
data: T;
}
// API 方法
export const Api = {
getList: (params: QueryParams) =>
request.get<ResponseData<PageResult<any>>>("/api/list", { params }),
create: (data: any) => request.post<ResponseData<any>>("/api/create", data),
update: (id: number, data: any) =>
request.put<ResponseData<any>>(`/api/update/${id}`, data),
delete: (id: number) =>
request.delete<ResponseData<any>>(`/api/delete/${id}`),
};
部署指南
1. 构建生产版本
# 安装依赖
npm install
# 构建生产版本
npm run build
2. 部署到 Web 服务器
将 dist 目录下的文件部署到 Web 服务器(如 Nginx、Apache)。
Nginx 配置示例
server {
listen 80;
server_name your-domain.com;
root /path/to/dist;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
location /api {
proxy_pass http://backend-server;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
3. 环境变量配置
在生产环境中,确保正确配置以下环境变量:
VITE_APP_BASE_API: API 基础路径VITE_APP_TITLE: 应用标题
常见问题
1. 开发环境问题
Q: 启动开发服务器失败 A: 检查 Node.js 版本是否 >= 16,确保所有依赖已正确安装。
Q: TypeScript 类型错误 A: 检查 tsconfig.json 配置,确保类型定义正确。
2. 构建问题
Q: 构建失败 A: 检查是否有 TypeScript 错误,确保所有依赖版本兼容。
Q: 生产环境 API 请求失败 A: 检查 API 基础路径配置,确保后端服务正常运行。
3. 性能优化
- 使用路由懒加载
- 组件按需导入
- 图片资源压缩
- 启用 Gzip 压缩
更新日志
v1.0.0
- 初始版本发布
- 基础功能实现
- 用户管理、角色管理、菜单管理等功能
- 集成 Element Plus UI 组件库
- 支持 JWT 认证
- 响应式布局设计
