feat():learning后台管理项目初始化
This commit is contained in:
yuj
336
discuss/QUICK_START.md
Normal file
336
discuss/QUICK_START.md
Normal file
@@ -0,0 +1,336 @@
|
||||
# 快速开发指南
|
||||
|
||||
## 添加新配置模块的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分钟
|
||||
Reference in New Issue
Block a user