# 快速开发指南 ## 添加新配置模块的5分钟快速步骤 假设要添加 `PaymentConfig` (支付配置) 模块。 ### 步骤 1: 创建模型 (30秒) **文件**: `internal/models/payment_config.go` 复制 `user_level_config.go`，替换类名和字段即可。 ### 步骤 2: 创建存储层 (1分钟) **文件**: `internal/storage/payment_config_storage.go` 复制 `user_level_config_storage.go`，改成新的模型名称。 ### 步骤 3: 创建服务层 (1分钟) **文件**: `internal/services/payment_config_service.go` 复制 `user_level_config_service.go`，改成新的存储和模型名称。 ### 步骤 4: 创建 Handler (1分钟) **文件**: `internal/api/handlers/payment_config_handler.go` 复制 `user_level_config_handler.go`，改成新的服务名称。 ### 步骤 5: 注册路由 (1分钟) 在 `internal/api/routes/routes.go` 中的 `SetupRoutes` 函数中添加： ```go paymentConfigHandler := handlers.NewPaymentConfigHandler(paymentConfigService, logger) paymentConfigs := admin.Group("/payment-configs") { paymentConfigs.GET("", paymentConfigHandler.List) paymentConfigs.POST("", paymentConfigHandler.Create) paymentConfigs.GET("/:id", paymentConfigHandler.GetByID) paymentConfigs.PUT("/:id", paymentConfigHandler.Update) paymentConfigs.DELETE("/:id", paymentConfigHandler.Delete) } ``` ### 步骤 6: 在 main.go 中注册服务 (30秒) ```go paymentConfigService := services.NewPaymentConfigService( storage.NewPaymentConfigStorage(), logger, ) router := routes.SetupRoutes( // ... 其他服务 paymentConfigService, // ... ) ``` ### 步骤 7: 添加数据库迁移 (30秒) 在 `internal/storage/database.go` 的 `AutoMigrate` 中： ```go err := DB.AutoMigrate( &models.UserLevelConfig{}, &models.PaymentConfig{}, // 新增 ) ``` --- ## 文件复制清单 使用这个检查清单确保没有遗漏： ``` [ ] 创建模型文件 internal/models/payment_config.go [ ] 定义主模型结构体 [ ] 定义 CreateRequest 结构体 [ ] 定义 UpdateRequest 结构体 [ ] 定义 ListRequest 结构体 [ ] 设置 TableName() [ ] 创建存储文件 internal/storage/payment_config_storage.go [ ] 定义接口 [ ] 实现 Create [ ] 实现 GetByID [ ] 实现 Update [ ] 实现 Delete [ ] 实现 List [ ] 创建服务文件 internal/services/payment_config_service.go [ ] 定义接口 [ ] 实现 Create（包含验证） [ ] 实现 GetByID [ ] 实现 Update [ ] 实现 Delete [ ] 实现 List [ ] 创建处理器 internal/api/handlers/payment_config_handler.go [ ] 实现 Create [ ] 实现 GetByID [ ] 实现 Update [ ] 实现 Delete [ ] 实现 List [ ] 在 routes.go 中注册路由 [ ] 在 SetupRoutes 函数签名中添加参数 [ ] 创建 Handler 实例 [ ] 定义路由组 [ ] 添加所有 CRUD 路由 [ ] 在 main.go 中注册服务 [ ] 创建 Storage 实例 [ ] 创建 Service 实例 [ ] 在 SetupRoutes 调用中传入 Service [ ] 在 database.go 中添加迁移 [ ] 在 AutoMigrate 中添加模型 ``` --- ## API 端点快速查询 ### 用户等级配置模块已有端点 ``` GET /api/admin/user-level-configs 列表（分页） GET /api/admin/user-level-configs/all 列表（不分页） POST /api/admin/user-level-configs 创建 GET /api/admin/user-level-configs/:id 详情 PUT /api/admin/user-level-configs/:id 更新 DELETE /api/admin/user-level-configs/:id 删除 PUT /api/admin/user-level-configs/:id/status 更新状态 ``` ### 新模块应该实现 ``` GET /api/admin/[resource-name] 列表（分页） POST /api/admin/[resource-name] 创建 GET /api/admin/[resource-name]/:id 详情 PUT /api/admin/[resource-name]/:id 更新 DELETE /api/admin/[resource-name]/:id 删除 ``` --- ## 常见错误排查 ### 1. 导包错误 确保在每个文件顶部都有正确的导入： ```go import ( "goalfymax-admin/internal/models" "goalfymax-admin/internal/storage" "goalfymax-admin/internal/services" "goalfymax-admin/pkg/utils" ) ``` ### 2. Handler 没有注册 - 在 `SetupRoutes` 中创建了 Handler 实例吗？ - Handler 实例是否传给了路由组？ ### 3. Service 没有注册 - 在 `main.go` 中创建了 Service 实例吗？ - Service 实例是否传给了 `SetupRoutes`？ ### 4. 迁移失败 - 模型定义中是否有 `TableName()` 方法？ - 是否在 `database.go` 的 `AutoMigrate` 中添加了模型？ ### 5. 字段验证不生效 检查请求模型中的 `binding` tag： - `required` - 必填 - `min=1,max=100` - 长度限制 - `email` - 邮箱格式 --- ## 测试新模块 ### 使用 curl 测试 ```bash # 创建 curl -X POST http://localhost:8087/api/admin/payment-configs \ -H "Content-Type: application/json" \ -d '{"key":"stripe_key","value":"sk_test_xxx","type":"string"}' # 列表 curl http://localhost:8087/api/admin/payment-configs # 详情 curl http://localhost:8087/api/admin/payment-configs/1 # 更新 curl -X PUT http://localhost:8087/api/admin/payment-configs/1 \ -H "Content-Type: application/json" \ -d '{"key":"stripe_key","value":"sk_test_yyy"}' # 删除 curl -X DELETE http://localhost:8087/api/admin/payment-configs/1 ``` --- ## 关键对比表 ### Models 文件 | 用户等级配置 | 新模块 | |-----------|--------| | `user_level_config.go` | `payment_config.go` | | `UserLevelConfig` | `PaymentConfig` | | `UserLevelConfigCreateRequest` | `PaymentConfigCreateRequest` | | `admin_user_level_configs` | `admin_payment_configs` | ### Storage 文件 | 用户等级配置 | 新模块 | |-----------|--------| | `user_level_config_storage.go` | `payment_config_storage.go` | | `UserLevelConfigStorage` | `PaymentConfigStorage` | | `NewUserLevelConfigStorage()` | `NewPaymentConfigStorage()` | ### Service 文件 | 用户等级配置 | 新模块 | |-----------|--------| | `user_level_config_service.go` | `payment_config_service.go` | | `UserLevelConfigService` | `PaymentConfigService` | | `NewUserLevelConfigService()` | `NewPaymentConfigService()` | ### Handler 文件 | 用户等级配置 | 新模块 | |-----------|--------| | `user_level_config_handler.go` | `payment_config_handler.go` | | `UserLevelConfigHandler` | `PaymentConfigHandler` | | `NewUserLevelConfigHandler()` | `NewPaymentConfigHandler()` | ### Routes 注册 | 用户等级配置 | 新模块 | |-----------|--------| | `/user-level-configs` | `/payment-configs` | | `userLevelConfigHandler` | `paymentConfigHandler` | | `userLevelConfigService` | `paymentConfigService` | --- ## 模板代码片段 ### 最小模型 ```go package models import "time" type PaymentConfig struct { ID uint `json:"id" gorm:"primaryKey;autoIncrement"` Key string `json:"key" gorm:"uniqueIndex;not null"` Value string `json:"value" gorm:"type:longtext"` CreatedAt time.Time `json:"created_at"` UpdatedAt time.Time `json:"updated_at"` } func (PaymentConfig) TableName() string { return "admin_payment_configs" } ``` ### 最小 Handler 方法 ```go func (h *PaymentConfigHandler) Create(c *gin.Context) { var req models.PaymentConfigCreateRequest if err := c.ShouldBindJSON(&req); err != nil { h.response.ValidateError(c, err) return } result, err := h.service.Create(&req) if err != nil { h.response.InternalServerError(c, err.Error()) return } h.response.Success(c, result) } ``` ### 最小 Service 方法 ```go func (s *paymentConfigService) Create(req *models.PaymentConfigCreateRequest) (*models.PaymentConfig, error) { config := &models.PaymentConfig{ Key: req.Key, Value: req.Value, } if err := s.storage.Create(config); err != nil { s.logger.Error("创建支付配置失败", zap.Error(err)) return nil, errors.New("创建失败") } return config, nil } ``` --- ## 内存关键点 1. **三层架构**: Handler -> Service -> Storage 2. **接口优先**: Service 和 Storage 都是接口 3. **命名规范**: `admin_[resource]s` 表名 4. **错误处理**: Service 返回有意义的错误，Handler 返回 HTTP 响应 5. **日志**: 每个操作都要记录日志 6. **验证**: Binding tag + Service 层验证 --- ## 下一步 如需添加新的配置模块，只需： 1. 复制现有配置模块（如 `user_level_config`） 2. 全量替换类名和结构 3. 调整业务逻辑验证（如果有的话） 4. 完成！ 预计耗时：5-10分钟