项目结构
CmdAdmin 采用前后端分离架构，后端使用 Spring Boot，前端使用 Vue 3。
后端结构
src/main/java/com/cmdadmin/
├── CmdAdminApplication.java # 应用启动类
├── common/ # 公共组件
│ ├── annotation/ # 自定义注解
│ │ ├── OperLog.java # 操作日志注解
│ │ └── DataScope.java # 数据权限注解
│ ├── aspect/ # AOP 切面
│ │ ├── OperLogAspect.java # 操作日志切面
│ │ └── DataScopeAspect.java # 数据权限切面
│ ├── base/ # 基础类
│ │ ├── BaseEntity.java # 实体基类
│ │ └── BaseController.java # 控制器基类
│ ├── config/ # 配置类
│ │ ├── RedisConfig.java # Redis 配置
│ │ ├── SecurityConfig.java # 安全配置
│ │ └── WebConfig.java # Web 配置
│ ├── constant/ # 常量定义
│ │ └── CommonConstant.java # 通用常量
│ ├── exception/ # 异常处理
│ │ ├── BusinessException.java # 业务异常
│ │ └── GlobalExceptionHandler.java # 全局异常处理
│ ├── filter/ # 过滤器
│ │ └── JwtAuthenticationFilter.java # JWT 认证过滤器
│ ├── response/ # 响应封装
│ │ └── Result.java # 统一响应
│ └── utils/ # 工具类
│ ├── JwtTokenUtil.java # JWT 工具
│ ├── SecurityUtils.java # 安全工具
│ └── ServletUtils.java # Servlet 工具
├── config/ # 外部配置
│ └── MyBatisConfig.java # MyBatis 配置
├── example/ # 示例模块
│ ├── controller/ # 示例控制器
│ ├── entity/ # 示例实体
│ ├── repository/ # 示例数据访问
│ └── service/ # 示例业务逻辑
└── system/ # 系统管理模块
├── controller/ # 系统控制器
│ ├── AuthController.java # 认证控制器
│ ├── SysUserController.java # 用户控制器
│ ├── SysRoleController.java # 角色控制器
│ ├── SysMenuController.java # 菜单控制器
│ ├── SysDeptController.java # 部门控制器
│ ├── SysDictTypeController.java # 字典类型控制器
│ ├── SysDictItemController.java # 字典项控制器
│ ├── SysParamController.java # 参数控制器
│ ├── SysNoticeController.java # 通知公告控制器
│ ├── SysJobController.java # 定时任务控制器
│ ├── SysLoginLogController.java # 登录日志控制器
│ ├── SysOperLogController.java # 操作日志控制器
│ └── SysExceptionLogController.java # 异常日志控制器
├── entity/ # 系统实体
│ ├── SysUser.java # 用户实体
│ ├── SysRole.java # 角色实体
│ ├── SysMenu.java # 菜单实体
│ ├── SysDept.java # 部门实体
│ ├── SysDictType.java # 字典类型实体
│ ├── SysDictItem.java # 字典项实体
│ ├── SysParam.java # 参数实体
│ ├── SysNotice.java # 通知公告实体
│ ├── SysJob.java # 定时任务实体
│ ├── SysLoginLog.java # 登录日志实体
│ ├── SysOperLog.java # 操作日志实体
│ └── SysExceptionLog.java # 异常日志实体
├── repository/ # 数据访问层
│ ├── SysUserRepository.java # 用户仓库
│ ├── SysRoleRepository.java # 角色仓库
│ └── ...
├── service/ # 业务逻辑层
│ ├── SysUserService.java # 用户服务
│ ├── SysRoleService.java # 角色服务
│ └── ...
└── job/ # 定时任务
├── CleanExpiredLogJob.java # 清理过期日志
├── CleanTempFileJob.java # 清理临时文件
├── DataSyncJob.java # 数据同步
└── ...前端结构
admin-web/
├── public/ # 静态资源
│ └── favicon.ico # 网站图标
├── src/
│ ├── api/ # API 接口
│ │ ├── auth.ts # 认证接口
│ │ ├── user.ts # 用户接口
│ │ ├── role.ts # 角色接口
│ │ ├── menu.ts # 菜单接口
│ │ └── ...
│ ├── assets/ # 静态资源
│ │ ├── images/ # 图片
│ │ ├── styles/ # 样式
│ │ └── icons/ # 图标
│ ├── components/ # 公共组件
│ │ ├── Dict/ # 字典组件
│ │ │ ├── DictSelect.vue # 字典下拉选择
│ │ │ ├── DictRadio.vue # 字典单选
│ │ │ └── DictTag.vue # 字典标签
│ │ ├── Breadcrumb/ # 面包屑
│ │ ├── Hamburger/ # 折叠按钮
│ │ ├── SvgIcon/ # SVG 图标
│ │ └── ...
│ ├── composables/ # 组合式函数
│ │ └── useCrud.ts # CRUD Hook
│ ├── directives/ # 自定义指令
│ │ └── permission.ts # 权限指令
│ ├── layout/ # 布局组件
│ │ ├── components/ # 布局子组件
│ │ │ ├── Navbar.vue # 顶部导航
│ │ │ ├── Sidebar/ # 侧边栏
│ │ │ ├── AppMain.vue # 主内容区
│ │ │ └── TagsView/ # 标签页
│ │ └── index.vue # 布局入口
│ ├── router/ # 路由配置
│ │ ├── index.ts # 路由入口
│ │ └── routes.ts # 静态路由
│ ├── services/ # 服务层
│ │ ├── request.ts # Axios 封装
│ │ └── modules/ # 业务模块
│ ├── stores/ # Pinia 状态
│ │ ├── auth.ts # 认证状态
│ │ ├── user.ts # 用户状态
│ │ ├── app.ts # 应用状态
│ │ └── tagsView.ts # 标签页状态
│ ├── utils/ # 工具函数
│ │ ├── auth.ts # 认证工具
│ │ ├── validate.ts # 验证工具
│ │ └── index.ts # 通用工具
│ ├── views/ # 页面视图
│ │ ├── login/ # 登录页
│ │ ├── dashboard/ # 仪表盘
│ │ ├── profile/ # 个人中心
│ │ ├── settings/ # 系统设置
│ │ ├── system/ # 系统管理
│ │ │ ├── user/ # 用户管理
│ │ │ ├── role/ # 角色管理
│ │ │ ├── menu/ # 菜单管理
│ │ │ ├── dept/ # 部门管理
│ │ │ ├── dict/ # 字典管理
│ │ │ ├── param/ # 参数管理
│ │ │ ├── notice/ # 通知公告
│ │ │ └── job/ # 定时任务
│ │ ├── monitor/ # 系统监控
│ │ │ ├── server/ # 服务器监控
│ │ │ └── cache/ # 缓存监控
│ │ ├── log/ # 日志管理
│ │ │ ├── login/ # 登录日志
│ │ │ ├── oper/ # 操作日志
│ │ │ └── error/ # 异常日志
│ │ └── example/ # 示例功能
│ │ ├── table/ # 表格示例
│ │ ├── form/ # 表单示例
│ │ ├── editor/ # 富文本编辑器
│ │ ├── monaco/ # 代码编辑器
│ │ ├── luckysheet/ # 在线表格
│ │ └── ...
│ ├── App.vue # 根组件
│ ├── main.ts # 入口文件
│ └── vite-env.d.ts # Vite 类型声明
├── .env.development # 开发环境配置
├── .env.production # 生产环境配置
├── index.html # HTML 模板
├── package.json # 依赖配置
├── tsconfig.json # TypeScript 配置
└── vite.config.ts # Vite 配置分层架构
后端分层
┌─────────────────────────────────────┐
│ Controller 层 │ ← 接收请求，返回响应
│ （处理 HTTP 请求，参数校验） │
├─────────────────────────────────────┤
│ Service 层 │ ← 业务逻辑处理
│ （业务规则，事务控制） │
├─────────────────────────────────────┤
│ Repository 层 │ ← 数据访问
│ （数据库操作，JPA） │
├─────────────────────────────────────┤
│ Entity 层 │ ← 数据模型
│ （实体类，与数据库表对应） │
└─────────────────────────────────────┘前端分层
┌─────────────────────────────────────┐
│ Views 层 │ ← 页面组件
│ （页面展示，用户交互） │
├─────────────────────────────────────┤
│ Components 层 │ ← 公共组件
│ （可复用组件） │
├─────────────────────────────────────┤
│ Stores 层 │ ← 状态管理
│ （Pinia，全局状态） │
├─────────────────────────────────────┤
│ Services 层 │ ← 服务层
│ （API 调用，数据处理） │
├─────────────────────────────────────┤
│ Utils 层 │ ← 工具函数
│ （通用工具，常量定义） │
└─────────────────────────────────────┘核心设计
1. 统一响应格式
java
public class Result<T> {
private Integer code; // 状态码 0-成功 1-失败
private String message; // 提示信息
private T data; // 数据
private Long timestamp; // 时间戳
}2. 统一异常处理
java
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(BusinessException.class)
public Result<Void> handleBusinessException(BusinessException e) {
return Result.error(e.getMessage());
}
@ExceptionHandler(Exception.class)
public Result<Void> handleException(Exception e) {
return Result.error("系统繁忙，请稍后重试");
}
}3. AOP 日志记录
java
@Aspect
@Component
public class OperLogAspect {
@Around("@annotation(operLog)")
public Object around(ProceedingJoinPoint point, OperLog operLog) {
// 记录操作前...
Object result = point.proceed();
// 记录操作后...
return result;
}
}4. 动态路由加载
typescript
// 自动扫描视图组件
const modules = import.meta.glob('@/views/**/*.vue')
// 动态注册路由
const registerRoutes = (menus: Menu[]) => {
menus.forEach(menu => {
const component = modules[`/src/views/${menu.component}.vue`]
// 注册路由...
})
}数据库设计
核心表关系
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ sys_user │────▶│sys_user_role│◀────│ sys_role │
└─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐
│sys_role_menu│
└─────────────┘
│
▼
┌─────────────┐
│ sys_menu │
└─────────────┘数据权限
┌─────────────┐ ┌─────────────┐
│ sys_user │────▶│ sys_dept │
│ dept_id │ │ id │
└─────────────┘ └─────────────┘
│
│ parent_id
▼
┌─────────────┐
│ sys_dept │
└─────────────┘配置文件
后端配置
| 文件 | 说明 |
|---|---|
application.yml | 公共配置 |
application-dev.yml | 开发环境 |
application-test.yml | 测试环境 |
application-prod.yml | 生产环境 |
前端配置
| 文件 | 说明 |
|---|---|
.env.development | 开发环境变量 |
.env.production | 生产环境变量 |
vite.config.ts | Vite 构建配置 |
tsconfig.json | TypeScript 配置 |
命名规范
后端命名
| 类型 | 规范 | 示例 |
|---|---|---|
| 包名 | 小写，点分隔 | com.cmdadmin.system |
| 类名 | 大驼峰 | SysUserController |
| 方法名 | 小驼峰 | getUserList |
| 变量名 | 小驼峰 | userName |
| 常量名 | 大写下划线 | MAX_RETRY_COUNT |
| 数据库表 | 小写下划线 | sys_user |
| 数据库字段 | 小写下划线 | user_name |
前端命名
| 类型 | 规范 | 示例 |
|---|---|---|
| 组件名 | 大驼峰 | UserManagement |
| 文件名 | 小写横线 | user-management.vue |
| 变量名 | 小驼峰 | userList |
| 常量名 | 大写下划线 | API_BASE_URL |
| 组合式函数 | use 前缀 | useCrud |
| Pinia Store | 名词 | useUserStore |