feat():learning后台管理项目初始化
This commit is contained in:
yuj
473
discuss/ARCHITECTURE_DIAGRAM.md
Normal file
473
discuss/ARCHITECTURE_DIAGRAM.md
Normal file
@@ -0,0 +1,473 @@
|
||||
# 架构可视化图
|
||||
|
||||
## 项目分层架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ HTTP 客户端 (前端/客户端) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Gin Web 框架 (routes.go) │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐
|
||||
│ │ 路由组 /api/admin/user-level-configs │
|
||||
│ │ 路由组 /api/admin/payment-configs │
|
||||
│ │ 路由组 /api/admin/general-configs │
|
||||
│ └─────────────────────────────────────────────────────────────┘
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────┼─────────┐
|
||||
▼ ▼ ▼
|
||||
┌───────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ User Level Config │ │ Payment Config │ │ General Config │
|
||||
│ Handler │ │ Handler │ │ Handler │
|
||||
└─────────┬─────────┘ └────────┬─────────┘ └────────┬────────┘
|
||||
│ │ │
|
||||
│ 调用 │ 调用 │ 调用
|
||||
▼ ▼ ▼
|
||||
┌───────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ UserLevelConfig │ │ PaymentConfig │ │ GeneralConfig │
|
||||
│ Service │ │ Service │ │ Service │
|
||||
│ (接口 + 实现) │ │ (接口 + 实现) │ │ (接口 + 实现) │
|
||||
│ │ │ │ │ │
|
||||
│ - Create() │ │ - Create() │ │ - Create() │
|
||||
│ - GetByID() │ │ - GetByID() │ │ - GetByID() │
|
||||
│ - Update() │ │ - Update() │ │ - Update() │
|
||||
│ - Delete() │ │ - Delete() │ │ - Delete() │
|
||||
│ - List() │ │ - List() │ │ - List() │
|
||||
└─────────┬─────────┘ └────────┬─────────┘ └────────┬────────┘
|
||||
│ │ │
|
||||
│ 调用 │ 调用 │ 调用
|
||||
▼ ▼ ▼
|
||||
┌───────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ UserLevelConfig │ │ PaymentConfig │ │ GeneralConfig │
|
||||
│ Storage │ │ Storage │ │ Storage │
|
||||
│ (接口 + 实现) │ │ (接口 + 实现) │ │ (接口 + 实现) │
|
||||
│ │ │ │ │ │
|
||||
│ - Create() │ │ - Create() │ │ - Create() │
|
||||
│ - GetByID() │ │ - GetByID() │ │ - GetByID() │
|
||||
│ - Update() │ │ - Update() │ │ - Update() │
|
||||
│ - Delete() │ │ - Delete() │ │ - Delete() │
|
||||
│ - List() │ │ - List() │ │ - List() │
|
||||
└─────────┬─────────┘ └────────┬─────────┘ └────────┬────────┘
|
||||
│ │ │
|
||||
│ 查询 │ 查询 │ 查询
|
||||
└────────────────────┼─────────────────────┘
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ MySQL 数据库 │
|
||||
│ │
|
||||
│ - admin_user_level_configs
|
||||
│ - admin_payment_configs
|
||||
│ - admin_general_configs
|
||||
│ - ... (其他表)
|
||||
└──────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 请求处理流程
|
||||
|
||||
```
|
||||
HTTP 请求
|
||||
│
|
||||
▼
|
||||
/api/admin/user-level-configs (GET)
|
||||
│
|
||||
▼
|
||||
Router.SetupRoutes()
|
||||
│
|
||||
├─ CORS 中间件
|
||||
├─ 日志中间件
|
||||
├─ 认证中间件 (RequireAuth)
|
||||
└─ RBAC 权限检查
|
||||
│
|
||||
▼
|
||||
Handler.List(c *gin.Context)
|
||||
│
|
||||
├─ 1. 验证请求参数 (c.ShouldBindQuery)
|
||||
│ └─ Binding 标签验证 (form:"page", default=1)
|
||||
│
|
||||
├─ 2. 调用 Service.List()
|
||||
│ └─ Service 层业务逻辑验证
|
||||
│
|
||||
└─ 3. 返回响应
|
||||
├─ 成功: response.Page(c, data, total, page, size)
|
||||
└─ 失败: response.InternalServerError(c, err)
|
||||
|
||||
HTTP 200 OK
|
||||
{
|
||||
"code": 0,
|
||||
"data": [...],
|
||||
"total": 10,
|
||||
"page": 1,
|
||||
"size": 20
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 文件依赖关系
|
||||
|
||||
```
|
||||
cmd/server/main.go
|
||||
│
|
||||
├─ 初始化 Database
|
||||
│ └─ internal/storage/database.go
|
||||
│ ├─ AutoMigrate()
|
||||
│ │ └─ &models.UserLevelConfig{}
|
||||
│ │ └─ &models.PaymentConfig{}
|
||||
│ └─ initDefaultXxxConfigs()
|
||||
│
|
||||
├─ 创建 Service 实例
|
||||
│ ├─ userLevelConfigService := services.NewUserLevelConfigService(
|
||||
│ │ └─ storage.NewUserLevelConfigStorage()
|
||||
│ │ └─ logger
|
||||
│ │ )
|
||||
│ │
|
||||
│ └─ internal/services/user_level_config_service.go
|
||||
│ └─ internal/storage/user_level_config_storage.go
|
||||
│ └─ internal/models/user_level_config.go
|
||||
│
|
||||
└─ 设置 Routes
|
||||
└─ internal/api/routes/routes.go
|
||||
├─ 创建所有 Handlers
|
||||
│ ├─ userLevelConfigHandler := handlers.New...()
|
||||
│ │ └─ internal/api/handlers/user_level_config_handler.go
|
||||
│ │
|
||||
│ └─ paymentConfigHandler := handlers.New...()
|
||||
│ └─ internal/api/handlers/payment_config_handler.go
|
||||
│
|
||||
└─ 定义所有路由组
|
||||
├─ userLevelConfigs := admin.Group("/user-level-configs")
|
||||
├─ paymentConfigs := admin.Group("/payment-configs")
|
||||
└─ ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三层架构详解
|
||||
|
||||
### 第一层: HTTP 处理层 (Handler/Controller)
|
||||
|
||||
**职责**:
|
||||
- 接收 HTTP 请求
|
||||
- 参数绑定和验证
|
||||
- 调用业务逻辑
|
||||
- 返回 HTTP 响应
|
||||
|
||||
**文件位置**: `internal/api/handlers/*_handler.go`
|
||||
|
||||
```go
|
||||
type UserLevelConfigHandler struct {
|
||||
service services.UserLevelConfigService
|
||||
response *utils.Response
|
||||
logger *utils.Logger
|
||||
}
|
||||
|
||||
func (h *UserLevelConfigHandler) List(c *gin.Context) {
|
||||
// 1. 参数绑定
|
||||
var req models.UserLevelConfigListRequest
|
||||
if err := c.ShouldBindQuery(&req); err != nil {
|
||||
h.response.ValidateError(c, err)
|
||||
return
|
||||
}
|
||||
|
||||
// 2. 调用业务逻辑
|
||||
configs, total, err := h.service.List(&req)
|
||||
|
||||
// 3. 返回响应
|
||||
h.response.Page(c, configs, total, req.Page, req.Size)
|
||||
}
|
||||
```
|
||||
|
||||
### 第二层: 业务逻辑层 (Service)
|
||||
|
||||
**职责**:
|
||||
- 实现业务逻辑
|
||||
- 数据验证
|
||||
- 事务管理
|
||||
- 调用数据访问层
|
||||
|
||||
**文件位置**: `internal/services/*_service.go`
|
||||
|
||||
```go
|
||||
type userLevelConfigService struct {
|
||||
storage storage.UserLevelConfigStorage
|
||||
logger *utils.Logger
|
||||
}
|
||||
|
||||
func (s *userLevelConfigService) Create(req *models.UserLevelConfigCreateRequest) (*models.UserLevelConfig, error) {
|
||||
// 1. 业务验证
|
||||
_, err := s.storage.GetByLevelCode(req.LevelCode)
|
||||
if err == nil {
|
||||
return nil, errors.New("等级代码已存在")
|
||||
}
|
||||
|
||||
// 2. 数据准备
|
||||
config := &models.UserLevelConfig{
|
||||
LevelName: req.LevelName,
|
||||
LevelCode: req.LevelCode,
|
||||
Status: 1,
|
||||
}
|
||||
|
||||
// 3. 调用存储层
|
||||
if err := s.storage.Create(config); err != nil {
|
||||
s.logger.Error("创建失败", zap.Error(err))
|
||||
return nil, errors.New("创建失败")
|
||||
}
|
||||
|
||||
// 4. 记录日志
|
||||
s.logger.Info("创建成功", zap.String("level_name", config.LevelName))
|
||||
return config, nil
|
||||
}
|
||||
```
|
||||
|
||||
### 第三层: 数据访问层 (Storage)
|
||||
|
||||
**职责**:
|
||||
- 数据库操作
|
||||
- 查询构建
|
||||
- 结果映射
|
||||
|
||||
**文件位置**: `internal/storage/*_storage.go`
|
||||
|
||||
```go
|
||||
type userLevelConfigStorage struct {
|
||||
db *gorm.DB
|
||||
}
|
||||
|
||||
func (s *userLevelConfigStorage) Create(config *models.UserLevelConfig) error {
|
||||
return s.db.Create(config).Error
|
||||
}
|
||||
|
||||
func (s *userLevelConfigStorage) List(req *models.UserLevelConfigListRequest) ([]models.UserLevelConfig, int64, error) {
|
||||
var configs []models.UserLevelConfig
|
||||
var total int64
|
||||
|
||||
query := s.db.Model(&models.UserLevelConfig{})
|
||||
|
||||
// 构建查询条件
|
||||
if req.LevelName != "" {
|
||||
query = query.Where("level_name LIKE ?", "%"+req.LevelName+"%")
|
||||
}
|
||||
|
||||
// 获取总数
|
||||
query.Count(&total)
|
||||
|
||||
// 分页查询
|
||||
offset := (req.Page - 1) * req.Size
|
||||
err := query.Order("sort_order ASC").Offset(offset).Limit(req.Size).Find(&configs).Error
|
||||
|
||||
return configs, total, err
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数据模型关系
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ admin_user_level_configs │
|
||||
├─────────────────────────────────────┤
|
||||
│ id (PK) │
|
||||
│ level_name (UK) ─────────┐ │
|
||||
│ level_code (UK) │ │
|
||||
│ project_limit │ │
|
||||
│ description │ │
|
||||
│ sort_order │ │
|
||||
│ status │ │
|
||||
│ created_at │ │
|
||||
│ updated_at │ │
|
||||
└─────────────────────────────────────┘
|
||||
│
|
||||
│
|
||||
┌────────┴─────────┐
|
||||
│ │
|
||||
(Model) │ │ (Model)
|
||||
UserLevelConfig │ │ GeneralConfig
|
||||
│ │
|
||||
└────────┬─────────┘
|
||||
│
|
||||
┌────────┴────────┐
|
||||
│ │
|
||||
(Database) │ │ (Database)
|
||||
admin_user_ │ │ admin_general_
|
||||
level_configs │ │ configs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 请求-响应周期
|
||||
|
||||
### 创建请求示例
|
||||
|
||||
```
|
||||
请求:
|
||||
POST /api/admin/user-level-configs
|
||||
Content-Type: application/json
|
||||
{
|
||||
"level_name": "VIP",
|
||||
"level_code": "vip",
|
||||
"project_limit": 10,
|
||||
"description": "VIP用户",
|
||||
"sort_order": 2
|
||||
}
|
||||
|
||||
处理流程:
|
||||
1. Routes 匹配到 POST /user-level-configs
|
||||
2. 创建 Handler 实例
|
||||
3. Handler.Create() 调用
|
||||
├─ 参数绑定: models.UserLevelConfigCreateRequest
|
||||
└─ 调用 Service.Create(req)
|
||||
4. Service.Create() 处理
|
||||
├─ 验证等级代码唯一性
|
||||
├─ 构建 UserLevelConfig 对象
|
||||
└─ 调用 Storage.Create(config)
|
||||
5. Storage.Create() 执行
|
||||
├─ 执行 SQL INSERT
|
||||
├─ 返回插入行数和错误
|
||||
└─ 将结果映射到 Go 对象
|
||||
6. 响应返回
|
||||
|
||||
响应:
|
||||
HTTP 200 OK
|
||||
Content-Type: application/json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"id": 1,
|
||||
"level_name": "VIP",
|
||||
"level_code": "vip",
|
||||
"project_limit": 10,
|
||||
"description": "VIP用户",
|
||||
"sort_order": 2,
|
||||
"status": 1,
|
||||
"created_at": "2024-10-28T13:25:00Z",
|
||||
"updated_at": "2024-10-28T13:25:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关键文件交互图
|
||||
|
||||
```
|
||||
main.go
|
||||
│
|
||||
├─ 加载配置
|
||||
│ └─ config/config.go
|
||||
│
|
||||
├─ 初始化数据库
|
||||
│ └─ storage/database.go
|
||||
│ └─ models/*.go (AutoMigrate)
|
||||
│
|
||||
├─ 创建 Services
|
||||
│ ├─ services/user_level_config_service.go
|
||||
│ │ └─ storage/user_level_config_storage.go
|
||||
│ │
|
||||
│ └─ services/payment_config_service.go
|
||||
│ └─ storage/payment_config_storage.go
|
||||
│
|
||||
└─ 设置 Routes
|
||||
└─ api/routes/routes.go
|
||||
├─ 创建 Handlers
|
||||
│ ├─ handlers/user_level_config_handler.go
|
||||
│ └─ handlers/payment_config_handler.go
|
||||
│
|
||||
└─ 定义路由
|
||||
├─ GET /api/admin/user-level-configs
|
||||
├─ POST /api/admin/user-level-configs
|
||||
├─ GET /api/admin/payment-configs
|
||||
├─ POST /api/admin/payment-configs
|
||||
└─ ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 菜单权限系统
|
||||
|
||||
```
|
||||
┌────────────────────────────────────┐
|
||||
│ admin_pages │ (菜单表)
|
||||
├────────────────────────────────────┤
|
||||
│ id (PK) │
|
||||
│ name (菜单名称) │
|
||||
│ path (菜单路径) │
|
||||
│ icon (菜单图标) │
|
||||
│ sort_order │
|
||||
│ is_active │
|
||||
└────────────────────────────────────┘
|
||||
│
|
||||
│ 1..N
|
||||
│
|
||||
├─────────────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌────────────────────┐ ┌──────────────────┐
|
||||
│ admin_roles │ │ admin_role_page_│
|
||||
│ │ │ permissions │
|
||||
├────────────────────┤ ├──────────────────┤
|
||||
│ id (PK) │ │ id (PK) │
|
||||
│ name │ │ role_id (FK) │
|
||||
│ level │ │ page_id (FK) │
|
||||
│ description │ │ created_at │
|
||||
└────────────────────┘ └──────────────────┘
|
||||
▲
|
||||
│ 1..N
|
||||
│
|
||||
┌────────────────────┐
|
||||
│ admin_users │
|
||||
├────────────────────┤
|
||||
│ id (PK) │
|
||||
│ username │
|
||||
│ email │
|
||||
│ role_id (FK) │
|
||||
│ status │
|
||||
└────────────────────┘
|
||||
|
||||
流程:
|
||||
1. User 拥有 Role
|
||||
2. Role 拥有多个 RolePagePermission
|
||||
3. RolePagePermission 关联 Page
|
||||
4. 权限检查时: User -> Role -> Permissions -> Accessible Pages
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 配置流程
|
||||
|
||||
```
|
||||
应用启动
|
||||
│
|
||||
├─ 1. 加载 YAML 配置
|
||||
│ └─ etc/config.yaml 或 etc/config-prod.yaml
|
||||
│ │
|
||||
│ ├─ server: { addr, port }
|
||||
│ ├─ database: { dsn, maxIdleConns, ... }
|
||||
│ ├─ gateway: { base_url, timeout, ... }
|
||||
│ ├─ sso: { sso_server_url, client_id, ... }
|
||||
│ ├─ log: { level, format, output }
|
||||
│ └─ message_push: { base_url, timeout, ... }
|
||||
│
|
||||
├─ 2. 解析到 Config 结构体
|
||||
│ └─ internal/config/config.go
|
||||
│ │
|
||||
│ ├─ ServerConfig
|
||||
│ ├─ DatabaseConfig
|
||||
│ ├─ GatewayConfig
|
||||
│ ├─ SSOConfig
|
||||
│ ├─ LogConfig
|
||||
│ └─ MessagePushConfig
|
||||
│
|
||||
└─ 3. 应用配置
|
||||
├─ 数据库连接
|
||||
├─ 日志初始化
|
||||
├─ 路由设置
|
||||
└─ 服务启动
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user