admin-vben/docs/开发文档.md

开发文档

开发环境搭建

环境要求

• Node.js: 18.0.0 或更高版本
• pnpm: 8.0.0 或更高版本
• Git: 2.0.0 或更高版本

安装步骤

1. 安装 Node.js

   # 下载并安装 Node.js 18+
   # 验证安装
   node --version
   npm --version
   

2. 安装 pnpm

   # 使用 npm 安装 pnpm
   npm install -g pnpm
   
   # 验证安装
   pnpm --version
   

3. 克隆项目

   git clone https://github.com/vbenjs/vue-vben-admin.git
   cd vue-vben-admin
   

4. 安装依赖

   # 安装项目依赖
   pnpm install
   

5. 启动开发服务器

   # 启动 Ant Design 版本
   pnpm dev:antd
   
   # 启动 Element Plus 版本
   pnpm dev:ele
   
   # 启动 Naive UI 版本
   pnpm dev:naive
   

项目结构说明

目录结构详解

yudao-ui-admin-vben/
├── apps/                    # 应用目录
│   ├── web-antd/           # Ant Design 版本
│   │   ├── src/            # 源代码
│   │   │   ├── api/        # API 接口
│   │   │   ├── components/ # 组件
│   │   │   ├── layouts/    # 布局
│   │   │   ├── router/     # 路由
│   │   │   ├── store/      # 状态管理
│   │   │   ├── utils/      # 工具函数
│   │   │   └── views/      # 页面视图
│   │   └── package.json    # 应用配置
│   ├── web-ele/            # Element Plus 版本
│   ├── web-naive/          # Naive UI 版本
│   └── backend-mock/       # 后端模拟服务
├── packages/               # 共享包目录
│   ├── @core/              # 核心功能
│   ├── constants/          # 常量定义
│   ├── effects/            # 副作用管理
│   ├── icons/              # 图标库
│   ├── locales/            # 国际化
│   ├── stores/             # 状态管理
│   ├── styles/             # 样式文件
│   ├── types/              # 类型定义
│   └── utils/              # 工具函数
└── internal/               # 内部配置
    ├── lint-configs/       # 代码规范
    ├── tailwind-config/    # Tailwind 配置
    ├── tsconfig/           # TypeScript 配置
    └── vite-config/        # Vite 配置

核心包说明

@core 包

• 基础组件封装
• 工具函数集合
• 类型定义扩展

stores 包

• 全局状态管理
• 用户信息存储
• 应用配置管理

utils 包

• 数据处理工具
• 日期时间工具
• 表单验证工具

开发规范

代码规范

1. 命名规范

• 文件命名: 使用 kebab-case (例如: user-info.vue)
• 组件命名: 使用 PascalCase (例如: UserInfo)
• 变量命名: 使用 camelCase (例如: userName)
• 常量命名: 使用 UPPER_SNAKE_CASE (例如: API_BASE_URL)

2. 组件规范

// 组件结构示例
<script setup lang="ts">
// 导入
import { ref, computed } from 'vue'
import { useUserStore } from '@/stores/user'

// 类型定义
interface Props {
  userId: number
  userName: string
}

// Props 定义
const props = defineProps<Props>()

// 状态管理
const userStore = useUserStore()
const loading = ref(false)

// 计算属性
const fullName = computed(() => `${props.userName} (${props.userId})`)

// 方法
const handleSubmit = async () => {
  loading.value = true
  try {
    await userStore.updateUser(props.userId, { name: props.userName })
  } finally {
    loading.value = false
  }
}
</script>

<template>
  <div class="user-info">
    <h3>{{ fullName }}</h3>
    <button :disabled="loading" @click="handleSubmit">
      {{ loading ? '保存中...' : '保存' }}
    </button>
  </div>
</template>

<style scoped>
.user-info {
  padding: 16px;
}
</style>

3. API 调用规范

// api/user.ts
import { request } from '@/utils/request'

export interface User {
  id: number
  name: string
  email: string
}

export const userApi = {
  // 获取用户列表
  getUsers: (params: { page: number; size: number }) => {
    return request.get<{ list: User[]; total: number }>('/api/users', { params })
  },
  
  // 创建用户
  createUser: (data: Omit<User, 'id'>) => {
    return request.post<User>('/api/users', data)
  },
  
  // 更新用户
  updateUser: (id: number, data: Partial<User>) => {
    return request.put<User>(`/api/users/${id}`, data)
  },
  
  // 删除用户
  deleteUser: (id: number) => {
    return request.delete(`/api/users/${id}`)
  }
}

样式规范

1. CSS 类命名

• 使用 BEM 命名规范
• 避免使用全局样式
• 优先使用 Tailwind CSS

/* BEM 示例 */
.user-list {}
.user-list__item {}
.user-list__item--active {}
.user-list__item__avatar {}

2. Tailwind CSS 使用

<template>
  <div class="p-4 bg-white rounded-lg shadow-sm">
    <h3 class="text-lg font-semibold text-gray-900 mb-4">用户信息</h3>
    <div class="space-y-3">
      <div class="flex items-center space-x-3">
        <span class="text-sm text-gray-500 w-20">姓名:</span>
        <span class="text-sm text-gray-900">{{ user.name }}</span>
      </div>
    </div>
  </div>
</template>

功能开发指南

1. 新增页面

步骤 1: 创建页面组件

# 在 apps/web-antd/src/views/ 下创建页面目录
mkdir -p apps/web-antd/src/views/user-management

步骤 2: 创建页面组件

<!-- apps/web-antd/src/views/user-management/index.vue -->
<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { userApi } from '@/api/user'

interface User {
  id: number
  name: string
  email: string
}

const users = ref<User[]>([])
const loading = ref(false)

const loadUsers = async () => {
  loading.value = true
  try {
    const response = await userApi.getUsers({ page: 1, size: 10 })
    users.value = response.data.list
  } finally {
    loading.value = false
  }
}

onMounted(() => {
  loadUsers()
})
</script>

<template>
  <div class="user-management">
    <h1>用户管理</h1>
    <div v-if="loading">加载中...</div>
    <div v-else>
      <table>
        <thead>
          <tr>
            <th>ID</th>
            <th>姓名</th>
            <th>邮箱</th>
          </tr>
        </thead>
        <tbody>
          <tr v-for="user in users" :key="user.id">
            <td>{{ user.id }}</td>
            <td>{{ user.name }}</td>
            <td>{{ user.email }}</td>
          </tr>
        </tbody>
      </table>
    </div>
  </div>
</template>

<style scoped>
.user-management {
  padding: 20px;
}
</style>

步骤 3: 配置路由

// apps/web-antd/src/router/routes.ts
import type { RouteRecordRaw } from 'vue-router'

export const routes: RouteRecordRaw[] = [
  // ... 其他路由
  {
    path: '/user-management',
    name: 'UserManagement',
    component: () => import('@/views/user-management/index.vue'),
    meta: {
      title: '用户管理',
      requiresAuth: true
    }
  }
]

2. 新增组件

创建可复用组件

<!-- apps/web-antd/src/components/UserAvatar.vue -->
<script setup lang="ts">
interface Props {
  user: {
    name: string
    avatar?: string
  }
  size?: 'small' | 'medium' | 'large'
}

const props = withDefaults(defineProps<Props>(), {
  size: 'medium'
})

const sizeMap = {
  small: 'w-8 h-8',
  medium: 'w-12 h-12',
  large: 'w-16 h-16'
}
</script>

<template>
  <div class="user-avatar flex items-center space-x-3">
    <img
      v-if="user.avatar"
      :src="user.avatar"
      :alt="user.name"
      :class="['rounded-full', sizeMap[size]]"
    />
    <div
      v-else
      :class="['bg-gray-200 rounded-full flex items-center justify-center', sizeMap[size]]"
    >
      <span class="text-gray-600 font-medium">{{ user.name.charAt(0) }}</span>
    </div>
    <span class="text-gray-900 font-medium">{{ user.name }}</span>
  </div>
</template>

<style scoped>
.user-avatar {
  display: inline-flex;
  align-items: center;
}
</style>

开发计划

第一阶段：基础功能开发 (1-2周)

任务清单

• 项目环境搭建
• 基础架构配置
• 用户登录功能
• 权限管理系统
• 基础布局组件

技术要点

• Vue3 Composition API 使用
• TypeScript 类型定义
• Pinia 状态管理
• Vue Router 路由配置

第二阶段：业务功能开发 (2-3周)

任务清单

• 用户管理模块
• 角色管理模块
• 菜单管理模块
• 系统设置模块
• 数据表格组件

技术要点

• 表单验证处理
• 表格数据展示
• 分页查询优化
• 文件上传下载

第三阶段：优化完善 (1周)

任务清单

• 性能优化
• 代码重构
• 测试用例编写
• 文档完善

技术要点

• 代码分割优化
• 懒加载实现
• 单元测试覆盖
• 文档自动生成

常见问题解决

1. 依赖安装问题

问题: pnpm install 失败 解决方案:

# 清理缓存
pnpm store prune

# 重新安装
pnpm install --force

2. 类型检查错误

问题: TypeScript 类型错误 解决方案:

# 检查类型错误
pnpm type-check

# 自动修复
pnpm lint:fix

3. 构建失败

问题: 生产构建失败 解决方案:

# 清理构建缓存
pnpm clean

# 重新构建
pnpm build

测试指南

单元测试

// __tests__/user.spec.ts
import { describe, it, expect } from 'vitest'
import { mount } from '@vue/test-utils'
import UserInfo from '@/components/UserInfo.vue'

describe('UserInfo', () => {
  it('renders user name correctly', () => {
    const wrapper = mount(UserInfo, {
      props: {
        user: {
          name: '张三',
          email: 'zhangsan@example.com'
        }
      }
    })
    
    expect(wrapper.text()).toContain('张三')
  })
})

E2E 测试

// __tests__/e2e/user.spec.ts
import { test, expect } from '@playwright/test'

test('user login flow', async ({ page }) => {
  await page.goto('/login')
  await page.fill('[data-testid="username"]', 'admin')
  await page.fill('[data-testid="password"]', '123456')
  await page.click('[data-testid="login-btn"]')
  
  await expect(page).toHaveURL('/dashboard')
})

部署指南

开发环境部署

# 启动开发服务器
pnpm dev:antd

# 访问地址
http://localhost:3000

生产环境部署

# 构建生产版本
pnpm build:antd

# 部署到服务器
# 将 dist 目录上传到 Web 服务器

性能优化

构建优化

• 代码分割
• 树摇优化
• 压缩资源
• 缓存策略

运行时优化

• 虚拟滚动
• 图片懒加载
• 组件懒加载
• 防抖节流

安全指南

前端安全

• XSS 防护
• CSRF 防护
• 输入验证
• 权限控制

代码安全

• 敏感信息加密
• API 密钥保护
• 代码混淆
• 安全审计

维护指南

日常维护

• 定期更新依赖
• 监控系统性能
• 备份重要数据
• 安全漏洞修复

版本管理

• 使用 Git 版本控制
• 遵循语义化版本
• 定期发布版本
• 维护更新日志