474 lines
17 KiB
Markdown
474 lines
17 KiB
Markdown
# 架构可视化图
|
|
|
|
## 项目分层架构
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 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. 应用配置
|
|
├─ 数据库连接
|
|
├─ 日志初始化
|
|
├─ 路由设置
|
|
└─ 服务启动
|
|
```
|
|
|