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