DukeDuke
主页
项目文档
技术文档
  • 单机版
  • 微服务
  • 代办项目
  • 优鲜项目
项目管理
关于我们
主页
项目文档
技术文档
  • 单机版
  • 微服务
  • 代办项目
  • 优鲜项目
项目管理
关于我们
  • 单体脚手架

    • 项目简介
    • 运行环境
    • 项目结构
    • 前端开发手册
    • 前端组件详解
    • 后端开发手册
    • 后端模块详解
    • 部署运维手册

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

安装步骤

  1. 克隆项目
git clone <repository-url>
cd duke-vue
  1. 安装依赖
npm install
  1. 启动开发服务器
npm run dev
  1. 构建生产版本
npm run build
  1. 预览生产版本
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 认证
  • 响应式布局设计
最近更新:: 2025/8/14 09:20
Contributors: Duke
Prev
项目结构
Next
前端组件详解