goalfylearning-admin/discuss/QUICK_START.md

快速开发指南

添加新配置模块的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 函数中添加：

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秒)

paymentConfigService := services.NewPaymentConfigService(
    storage.NewPaymentConfigStorage(),
    logger,
)

router := routes.SetupRoutes(
    // ... 其他服务
    paymentConfigService,
    // ...
)

步骤 7: 添加数据库迁移 (30秒)

在 internal/storage/database.go 的 AutoMigrate 中：

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. 导包错误

确保在每个文件顶部都有正确的导入：

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 测试

# 创建
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

---

模板代码片段

最小模型

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 方法

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 方法

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分钟