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