项目结构
本文档介绍 Vben Admin 项目的目录结构和文件组织方式。
整体结构
vben-admin/
├── vben-boot/ # 后端项目（Spring Boot）
│ ├── vben-admin/ # 启动模块
│ ├── vben-common/ # 公共模块
│ ├── vben-system/ # 系统模块
│ ├── vben-generator/ # 代码生成模块
│ ├── vben-quartz/ # 定时任务模块
│ └── sql/ # 数据库脚本
├── vue-vben-admin/ # 前端项目（Vue 3）
│ ├── apps/ # 应用目录
│ ├── packages/ # 公共包
│ ├── internal/ # 内部工具
│ └── docs/ # 文档
└── docs-site/ # 文档网站后端结构
vben-boot 目录
vben-boot/
├── vben-admin/ # 启动模块
│ ├── src/main/java/
│ │ └── com/vben/
│ │ ├── VbenApplication.java # 启动类
│ │ ├── controller/ # 控制器
│ │ ├── service/ # 服务层
│ │ └── config/ # 配置类
│ └── src/main/resources/
│ ├── application.yml # 配置文件
│ └── logback-spring.xml # 日志配置
├── vben-common/ # 公共模块
│ └── src/main/java/
│ └── com/vben/common/
│ ├── annotation/ # 注解
│ ├── config/ # 配置
│ ├── constant/ # 常量
│ ├── core/ # 核心类
│ ├── enums/ # 枚举
│ ├── exception/ # 异常
│ ├── utils/ # 工具类
│ └── validator/ # 验证器
├── vben-system/ # 系统模块
│ └── src/main/java/
│ └── com/vben/system/
│ ├── controller/ # 系统控制器
│ ├── domain/ # 实体类
│ ├── mapper/ # Mapper
│ ├── service/ # 服务
│ └── vo/ # VO 对象
└── sql/ # 数据库脚本
├── common_vben_sql.sql # 基础表结构
└── sys_region.sql # 地区数据前端结构
vue-vben-admin 目录
vue-vben-admin/
├── apps/ # 应用目录
│ ├── web-antd/ # Ant Design Vue 版本
│ │ ├── src/
│ │ │ ├── api/ # API 接口
│ │ │ ├── assets/ # 静态资源
│ │ │ ├── components/ # 组件
│ │ │ ├── layouts/ # 布局
│ │ │ ├── locales/ # 国际化
│ │ │ ├── router/ # 路由
│ │ │ ├── store/ # 状态管理
│ │ │ ├── styles/ # 样式
│ │ │ ├── utils/ # 工具函数
│ │ │ ├── views/ # 页面
│ │ │ ├── app.vue # 根组件
│ │ │ └── main.ts # 入口文件
│ │ ├── index.html
│ │ ├── package.json
│ │ └── vite.config.mts
│ ├── web-ele/ # Element Plus 版本
│ ├── web-naive/ # Naive UI 版本
│ └── backend-mock/ # Mock 服务
├── packages/ # 公共包
│ ├── @core/ # 核心包
│ │ ├── base/ # 基础功能
│ │ ├── composables/ # 组合式函数
│ │ ├── preferences/ # 偏好设置
│ │ └── ui-kit/ # UI 组件
│ ├── constants/ # 常量
│ ├── effects/ # 副作用
│ │ ├── access/ # 权限
│ │ ├── common-ui/ # 通用 UI
│ │ ├── hooks/ # Hooks
│ │ ├── layouts/ # 布局
│ │ ├── plugins/ # 插件
│ │ └── request/ # 请求
│ ├── icons/ # 图标
│ ├── locales/ # 国际化
│ ├── stores/ # 状态管理
│ ├── styles/ # 样式
│ ├── types/ # 类型定义
│ └── utils/ # 工具函数
└── internal/ # 内部工具
├── lint-configs/ # 代码规范配置
├── node-utils/ # Node 工具
├── tailwind-config/ # Tailwind 配置
├── tsconfig/ # TypeScript 配置
└── vite-config/ # Vite 配置核心目录说明
API 目录
src/api/
├── auth/ # 认证相关
│ ├── login.ts
│ └── user.ts
├── system/ # 系统管理
│ ├── user.ts
│ ├── role.ts
│ ├── menu.ts
│ └── dept.ts
└── index.ts # API 统一导出组件目录
src/components/
├── ImageUpload/ # 图片上传
├── FileUpload/ # 文件上传
├── RichEditor/ # 富文本编辑器
├── MarkdownEditor/ # Markdown 编辑器
├── CodeEditor/ # 代码编辑器
├── RegionPicker/ # 地区选择器
├── VbenChart/ # 图表组件
├── VbenImagePreview/ # 图片预览
└── VbenPdfPreview/ # PDF 预览路由目录
src/router/
├── routes/ # 路由配置
│ ├── core.ts # 核心路由
│ ├── modules/ # 模块路由
│ │ ├── dashboard.ts
│ │ ├── system.ts
│ │ └── ...
│ └── index.ts
├── guard/ # 路由守卫
│ ├── permission.ts
│ └── state.ts
└── index.ts # 路由入口Store 目录
src/store/
├── modules/ # 模块
│ ├── user.ts # 用户信息
│ ├── app.ts # 应用配置
│ ├── permission.ts # 权限
│ └── tabs.ts # 标签页
└── index.ts # Store 入口工具目录
src/utils/
├── auth/ # 认证工具
├── cache/ # 缓存工具
├── http/ # HTTP 工具
├── is/ # 类型判断
├── format/ # 格式化
├── validate/ # 验证
└── index.ts配置文件
后端配置
yaml
# application.yml
spring:
datasource:
url: jdbc:mysql://localhost:3306/vben_admin
username: root
password: password
redis:
host: localhost
port: 6379
mybatis-plus:
mapper-locations: classpath*:/mapper/**/*.xml
type-aliases-package: com.vben.**.domain
sa-token:
token-name: Authorization
timeout: 2592000
is-concurrent: true前端配置
typescript
// vite.config.mts
export default defineConfig({
server: {
port: 5173,
proxy: {
'/api': {
target: 'http://localhost:8080',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '')
}
}
}
});文件命名规范
后端
- Java 类：大驼峰命名，如
UserController.java - 接口：I 开头，如
IUserService.java - 实体类：与表名对应，如
SysUser.java - Mapper：实体名 + Mapper，如
UserMapper.java
前端
- 组件：大驼峰命名，如
UserList.vue - 工具函数：小驼峰命名，如
formatDate.ts - 常量：全大写下划线，如
API_BASE_URL - 类型定义：大驼峰命名，如
UserInfo.ts
模块划分
后端模块
- vben-common：公共模块，提供基础功能
- vben-system：系统管理模块
- vben-generator：代码生成模块
- vben-quartz：定时任务模块
- vben-admin：启动模块，整合所有功能
前端模块
- @core：核心功能包
- effects：副作用包（权限、请求等）
- packages：业务包（组件、工具等）
- apps：应用包（不同 UI 框架版本）
开发建议
- 模块化开发：按功能模块组织代码
- 组件复用：提取公共组件到 packages
- 类型安全：使用 TypeScript 定义类型
- 代码规范：遵循 ESLint 和 Prettier 规范
- 文档完善：为关键功能编写文档