20 KiB
20 KiB
系统架构文档
本文档描述 Goravel Admin 后台管理系统的整体架构设计。
目录
系统概览
┌─────────────────────────────────────────────────────────────────┐
│ 客户端 (Browser) │
├─────────────────────────────────────────────────────────────────┤
│ Vue 3 SPA (Element Plus) │
├─────────────────────────────────────────────────────────────────┤
│ Nginx / CDN │
├─────────────────────────────────────────────────────────────────┤
│ Goravel API Server │
├─────────────────────────────────────────────────────────────────┤
│ MySQL / PostgreSQL │ Redis │
└─────────────────────────────────────────────────────────────────┘
技术架构
技术栈
| 层级 | 技术 | 版本 |
|---|---|---|
| 后端框架 | Goravel | v1.14+ |
| 编程语言 | Go | 1.21+ |
| 前端框架 | Vue | 3.4+ |
| UI 组件 | Element Plus | 2.4+ |
| 表格组件 | VXE-Table | 4.7+ |
| 状态管理 | Pinia | 2.1+ |
| 数据库 | MySQL/PostgreSQL | 8.0+ / 15+ |
| 缓存 | Redis | 7.0+ |
| 认证 | JWT | - |
架构模式
┌─────────────────────────────────────────────────────────────────┐
│ 前端 (Vue 3) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Views │ │Components│ │Composables│ │ Store (Pinia) │ │
│ └────┬─────┘ └────┬─────┘ └────┬──────┘ └────────┬─────────┘ │
│ └─────────────┴─────────────┴─────────────────┘ │
│ │ API │
├──────────────────────────────┼──────────────────────────────────┤
│ 后端 (Goravel) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Controllers │ │ Middleware │ │ Routes │ │
│ └──────┬───────┘ └──────┬───────┘ └──────────────────────┘ │
│ │ │ │
│ ┌──────▼───────┐ ┌──────▼───────┐ │
│ │ Services │ │ Helpers │ │
│ └──────┬───────┘ └──────────────┘ │
│ │ │
│ ┌──────▼───────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ Models │ │ Events │ │ Jobs │ │
│ └──────┬───────┘ └──────────────┘ └──────────────────────┘ │
├─────────┼───────────────────────────────────────────────────────┤
│ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Database │ │ Redis │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
后端架构
目录结构
app/
├── console/ # 命令行
│ └── commands/ # 自定义命令
├── http/
│ ├── controllers/ # 控制器
│ │ └── admin/ # 后台管理控制器
│ ├── middleware/ # 中间件
│ ├── requests/ # 请求验证
│ ├── helpers/ # 辅助函数
│ ├── response/ # 统一响应
│ └── trans/ # 翻译工具
├── models/ # 数据模型
├── services/ # 业务逻辑
├── utils/ # 工具函数
│ ├── logger/ # 日志工具
│ ├── traceid/ # 链路追踪
│ └── errorlog/ # 错误日志
├── events/ # 事件
├── listeners/ # 事件监听器
├── jobs/ # 队列任务
├── providers/ # 服务提供者
├── rules/ # 自定义验证规则
└── websocket/ # WebSocket
└── notifications/ # 通知推送
分层架构
1. 控制器层 (Controllers)
负责接收请求、验证参数、调用服务、返回响应。
// app/http/controllers/admin/admin_controller.go
func (a *AdminController) Index(ctx http.Context) http.Response {
// 1. 获取查询参数
// 2. 调用 Service 获取数据
// 3. 返回统一响应
}
2. 服务层 (Services)
封装业务逻辑，可被多个控制器复用。
// app/services/admin_service.go
type AdminService struct{}
func (s *AdminService) GetAdminWithRoles(id uint) (*models.Admin, error) {
// 业务逻辑处理
}
3. 模型层 (Models)
定义数据结构和数据库映射。
// app/models/admin.go
type Admin struct {
orm.Model
Username string `gorm:"size:50;uniqueIndex" json:"username"`
Password string `gorm:"size:255" json:"-"`
Roles []*Role `gorm:"many2many:admin_role" json:"roles,omitempty"`
}
4. 中间件层 (Middleware)
处理认证、权限、日志等横切关注点。
// 中间件执行顺序
Request → TraceID → JWT Auth → Permission → Controller → OperationLog → Response
核心中间件：
| 中间件 | 功能 |
|---|---|
jwt.go |
JWT 认证 |
permission.go |
权限验证 |
operation_log.go |
操作日志记录 |
blacklist.go |
IP 黑名单检查 |
rate_limiter.go |
请求限流 |
trace_id.go |
链路追踪 |
统一响应
// 成功响应
response.Success(ctx, data)
// 错误响应
response.Error(ctx, http.StatusBadRequest, "错误信息")
// 泛型查找
admin, resp := response.FindByID[models.Admin](ctx, id, nil)
前端架构
目录结构
html/src/
├── api/ # API 请求
├── components/ # 通用组件
│ ├── SearchForm.vue # 搜索表单
│ ├── Pagination.vue # 分页组件
│ ├── ErrorBoundary.vue # 错误边界
│ └── ColumnSettingDialog.vue # 列设置
├── composables/ # 可复用逻辑 (TypeScript)
│ ├── useCrud.ts # CRUD 操作
│ ├── useDebounce.ts # 防抖
│ ├── useTableSort.ts # 表格排序
│ ├── usePermission.ts # 权限检查
│ ├── useListPage.js # 列表页面
│ └── useColumnSetting.js # 列设置
├── i18n/ # 国际化
│ └── locales/
│ ├── zh-CN.json
│ └── en-US.json
├── layouts/ # 布局组件
├── router/ # 路由配置
├── store/ # 状态管理 (Pinia)
│ ├── user.js # 用户状态
│ ├── app.js # 应用状态
│ └── tabs.js # 标签页状态
├── types/ # TypeScript 类型
│ ├── index.d.ts # 实体类型
│ └── composables.d.ts # Composable 类型
├── utils/ # 工具函数
│ ├── request.js # Axios 封装
│ ├── storage.js # 存储工具
│ └── validation.js # 验证器
└── views/ # 页面组件
├── admin/
├── role/
├── menu/
└── ...
Composables 设计
核心 Composables 采用 TypeScript 编写，提供完整类型支持：
// useCrud.ts - CRUD 操作封装
const {
dialogVisible, // 对话框状态
editId, // 编辑ID
handleAdd, // 添加
handleEdit, // 编辑
handleDelete, // 删除
handleBatchDelete // 批量删除
} = useCrud({ deleteApi, batchDeleteApi })
// usePermission.ts - 权限检查
const {
hasPermission, // 检查权限
shouldShowButton, // 是否显示按钮
getButtonState // 获取按钮状态
} = usePermission()
状态管理
┌─────────────────────────────────────────┐
│ Pinia Store │
├─────────────┬─────────────┬─────────────┤
│ userStore │ appStore │ tabsStore │
├─────────────┼─────────────┼─────────────┤
│ - userInfo │ - sidebar │ - tabs │
│ - token │ - fullscreen│ - activeTab │
│ - menus │ - language │ │
│ - permissions│ │ │
└─────────────┴─────────────┴─────────────┘
数据库设计
ER 图
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ admins │─────│ admin_role │─────│ roles │
├─────────────┤ ├─────────────┤ ├─────────────┤
│ id │ │ admin_id │ │ id │
│ username │ │ role_id │ │ name │
│ password │ └─────────────┘ │ slug │
│ department_id│ │ status │
└──────┬──────┘ └──────┬──────┘
│ │
│ ┌─────────────┐ │
│ │ departments │ │
└────┤ │ ┌─────────────┴─────────────┐
│ id │ │ role_permission │
│ name │ ├───────────────────────────┤
│ parent_id │ │ role_id │
└─────────────┘ │ permission_id │
└─────────────┬─────────────┘
│
┌─────────────▼─────────────┐
│ permissions │
├───────────────────────────┤
│ id │
│ name │
│ slug │
│ method │
│ path │
│ menu_id │
└───────────────────────────┘
核心表结构
| 表名 | 说明 |
|---|---|
admins |
管理员 |
roles |
角色 |
permissions |
权限 |
menus |
菜单 |
departments |
部门 |
dictionaries |
字典 |
blacklists |
黑名单 |
operation_logs |
操作日志 |
login_logs |
登录日志 |
system_logs |
系统日志 |
personal_access_tokens |
Token 管理 |
notifications |
通知 |
attachments |
附件 |
exports |
导出任务 |
安全架构
认证流程
┌─────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Login │───▶│ Validate │───▶│ Generate │───▶│ Return │
│ Request │ │ Credentials │ │ JWT │ │ Token │
└─────────┘ └─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐
│ Rate Limit │
│ Check │
└─────────────┘
权限验证流程
Request → JWT Middleware → Permission Middleware → Controller
│ │
▼ ▼
验证 Token 检查权限
│ │
▼ ▼
解析用户信息 匹配路由权限
│ │
▼ ▼
写入 Context 允许/拒绝
安全特性
| 特性 | 实现方式 |
|---|---|
| 认证 | JWT Token + 滑动过期 |
| 授权 | RBAC 权限模型 |
| 限流 | Token Bucket 算法 |
| 黑名单 | IP/Token 双重黑名单 |
| 日志 | 操作/登录日志全记录 |
| 追踪 | TraceID 链路追踪 |
| 敏感字段 | 密码等字段 json:"-" |
部署架构
单机部署
┌────────────────────────────────────────┐
│ Server │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Nginx │──│ Goravel │──│ MySQL │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │ │
│ ┌────▼────┐ │
│ │ Redis │ │
│ └─────────┘ │
└────────────────────────────────────────┘
高可用部署
┌─────────────┐
│ Client │
└──────┬──────┘
│
┌──────▼──────┐
│ CDN │
└──────┬──────┘
│
┌──────▼──────┐
│ Load Balancer│
└──────┬──────┘
┌───────────────┼───────────────┐
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ Goravel │ │ Goravel │ │ Goravel │
│ Server 1 │ │ Server 2 │ │ Server 3 │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└───────────────┼───────────────┘
│
┌────────────┼────────────┐
│ │
┌──────▼──────┐ ┌──────▼──────┐
│ MySQL Master│──────────│ Redis Cluster│
└──────┬──────┘ └──────────────┘
│
┌──────▼──────┐
│ MySQL Slave │
└─────────────┘
Docker 部署
# docker-compose.yml
version: '3.8'
services:
app:
build: .
ports:
- "3000:3000"
depends_on:
- mysql
- redis
mysql:
image: mysql:8.0
volumes:
- mysql_data:/var/lib/mysql
redis:
image: redis:7-alpine
volumes:
- redis_data:/data
性能优化
后端优化
| 优化项 | 实现 |
|---|---|
| 数据库连接池 | 配置合理的连接数 |
| 查询优化 | 预加载关联、索引优化 |
| 缓存策略 | Redis 缓存热点数据 |
| 日志分级 | Debug/Info 分离 |
前端优化
| 优化项 | 实现 |
|---|---|
| 虚拟滚动 | VXE-Table 大数据渲染 |
| 代码分割 | 路由懒加载 |
| 状态管理 | Pinia 响应式优化 |
| 防抖节流 | useDebounce composable |
扩展指南
添加新模块
-
后端
- 创建 Model:
app/models/xxx.go - 创建 Controller:
app/http/controllers/admin/xxx_controller.go - 创建 Request:
app/http/requests/admin/xxx_request.go - 注册路由:
routes/admin.go
- 创建 Model:
-
前端
- 创建 API:
html/src/api/xxx.js - 创建页面:
html/src/views/xxx/XxxList.vue - 创建表单:
html/src/views/xxx/XxxForm.vue - 注册路由:
html/src/router/index.js
- 创建 API:
添加新权限
- 数据库添加权限记录 (
permissions表) - 关联到菜单 (
menu_id) - 分配给角色 (
role_permission表)