# 蜜糖-脚本任务

**Repository Path**: portable/honey-ad-script

## Basic Information

- **Project Name**: 蜜糖-脚本任务
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-19
- **Last Updated**: 2026-01-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Ad Script

一个基于 Go 的脚本队列任务系统，支持定时任务调度、API 接口服务和消息队列消费。

## 特性

- **定时任务调度** - 基于 cron 表达式的灵活任务调度
- **多入口部署** - 支持完整服务、纯 API、纯 Worker、单脚本执行
- **数据持久化** - MySQL + GORM，完整的任务执行日志
- **缓存支持** - Redis 缓存封装
- **消息队列** - RabbitMQ 异步任务处理
- **RESTful API** - 基于 Gin 的 HTTP 接口
- **任务管理** - API 手动触发、任务状态查询、统计分析

## 技术栈

| 组件 | 技术栈 |
|------|--------|
| Web 框架 | [Gin](https://github.com/gin-gonic/gin) |
| ORM | [GORM](https://github.com/go-gorm/gorm) |
| 调度器 | [robfig/cron](https://github.com/robfig/cron) |
| 数据库 | MySQL 8.0+ |
| 缓存 | Redis 6.0+ |
| 消息队列 | RabbitMQ 3.8+ |
| 配置管理 | [Viper](https://github.com/spf13/viper) |
| 日志 | [zap](https://github.com/uber-go/zap) |

## 项目结构

```
ad_script/
├── cmd/                    # 入口程序
│   ├── server/            # 完整服务（API + 调度器）
│   ├── api/               # 仅 API 服务
│   ├── worker/            # 仅 Worker（消费队列）
│   └── run/               # 单独运行指定脚本
│
├── internal/              # 私有应用代码
│   ├── api/              # HTTP API
│   ├── scheduler/        # 定时调度器
│   ├── runner/           # 任务执行器
│   ├── queue/            # RabbitMQ 封装
│   ├── models/           # 数据模型
│   ├── repository/       # 数据访问层
│   ├── cache/            # Redis 缓存
│   └── config/           # 配置管理
│
├── scripts/              # 任务脚本实现
├── pkg/                  # 公共库
├── configs/              # 配置文件
└── migrations/           # 数据库迁移
```

## 快速开始

### 1. 环境准备

确保已安装：
- Go 1.22+
- MySQL 8.0+
- Redis 6.0+
- RabbitMQ 3.8+ (可选)

### 2. 安装依赖

```bash
go mod download
```

### 3. 配置数据库

创建数据库并执行迁移：

```bash
mysql -u root -p < migrations/001_init.sql
```

### 4. 修改配置

编辑 `configs/config.yaml`，修改数据库、Redis、RabbitMQ 连接信息：

```yaml
database:
  host: "127.0.0.1"
  port: 3306
  username: "root"
  password: "your_password"
  database: "ad_script"

redis:
  host: "127.0.0.1"
  port: 6379
  password: ""

rabbitmq:
  host: "127.0.0.1"
  port: 5672
  username: "guest"
  password: "guest"
```

### 5. 运行服务

#### 启动完整服务（API + 定时调度）

```bash
go run cmd/server/main.go
```

#### 仅启动 API 服务

```bash
go run cmd/api/main.go
```

#### 仅启动 Worker

```bash
go run cmd/worker/main.go
```

#### 单独运行某个任务

```bash
# 列出所有可用任务
go run cmd/run/main.go --list

# 执行指定任务
go run cmd/run/main.go --task=cleanup_logs
```

## API 接口

### 健康检查

```bash
GET /health
```

### 用户管理

```bash
# 创建用户
POST /api/v1/users
Content-Type: application/json

{
  "username": "testuser",
  "email": "test@example.com",
  "password": "password123",
  "nickname": "测试用户"
}

# 获取用户列表
GET /api/v1/users?page=1&page_size=10

# 获取用户详情
GET /api/v1/users/:id

# 更新用户
PUT /api/v1/users/:id
Content-Type: application/json

{
  "nickname": "新昵称",
  "status": 1
}

# 删除用户
DELETE /api/v1/users/:id
```

### 任务管理

```bash
# 获取所有任务
GET /api/v1/tasks

# 手动触发任务
POST /api/v1/tasks/:name/trigger
Content-Type: application/json

{
  "args": {
    "key": "value"
  }
}

# 获取任务执行日志
GET /api/v1/tasks/logs?page=1&page_size=20&task_name=cleanup_logs

# 获取任务统计
GET /api/v1/tasks/stats?task_name=cleanup_logs&days=7
```

## 编写任务脚本

### 1. 创建任务

在 `scripts/` 目录下创建新的任务文件，例如 `my_task.go`：

```go
package scripts

import (
    "ad_script/internal/runner"
    "go.uber.org/zap"
    "time"
)

// MyTask 我的任务
type MyTask struct{}

// Name 任务名称
func (t *MyTask) Name() string {
    return "my_task"
}

// Description 任务描述
func (t *MyTask) Description() string {
    return "这是一个示例任务"
}

// Run 执行任务
func (t *MyTask) Run(ctx *runner.TaskContext) error {
    ctx.Info("任务开始执行")

    // 获取参数
    param := ctx.GetArg("param_name")

    // 业务逻辑
    time.Sleep(1 * time.Second)

    ctx.Info("任务执行成功", zap.String("param", param))
    return nil
}
```

### 2. 注册任务

在 `scripts/registry.go` 中注册任务：

```go
func init() {
    // 注册任务并设置 cron 表达式（可选）
    scheduler.RegisterTask(&MyTask{}, "0 */5 * * * ?")  // 每 5 分钟执行一次
}
```

### 3. Cron 表达式格式

本项目使用秒级精度的 cron 表达式：

```
格式: 秒 分 时 日 月 周
示例: 0 0 2 * * ?    # 每天凌晨 2 点
示例: 0 */5 * * * ?   # 每 5 分钟
示例: 0 0 0 * * ?     # 每天凌晨 0 点
```

## 示例任务

项目包含两个示例任务：

### cleanup_logs

清理过期日志任务，每天凌晨 2 点执行。

```bash
go run cmd/run/main.go --task=cleanup_logs
```

### data_sync

同步用户数据到 Redis，每小时执行一次。

```bash
go run cmd/run/main.go --task=data_sync
```

## 数据库操作示例

### GORM 查询

```go
import (
    "ad_script/internal/config"
    "ad_script/internal/models"
)

// 查询单个用户
var user models.User
config.DB.First(&user, 1)
config.DB.Where("username = ?", "admin").First(&user)

// 查询列表
var users []models.User
config.DB.Offset(0).Limit(10).Find(&users)

// 创建
user := &models.User{
    Username: "test",
    Email:    "test@example.com",
    Password: "123456",
}
config.DB.Create(user)

// 更新
config.DB.Model(&user).Update("nickname", "新昵称")

// 删除（软删除）
config.DB.Delete(&user)
```

### Redis 操作

```go
import "ad_script/internal/cache"

// 设置缓存
cache.Set("key", "value", 1*time.Hour)

// 获取缓存
val, err := cache.Get("key")

// 删除缓存
cache.Del("key")

// 哈希操作
cache.HSet("user:1", "name", "张三")
name, _ := cache.HGet("user:1", "name")
```

### RabbitMQ 操作

```go
import "ad_script/internal/queue"

// 发布消息
queue.Publish(context.Background(), "task_queue", []byte("message"))

// 消费消息（在 Worker 中自动处理）
msgs, _ := queue.Consume("task_queue", false)
for msg := range msgs {
    // 处理消息
    msg.Ack(false)
}
```

## 部署

### 编译

```bash
# 编译 server
go build -o bin/server cmd/server/main.go

# 编译 api
go build -o bin/api cmd/api/main.go

# 编译 worker
go build -o bin/worker cmd/worker/main.go

# 编译 run
go build -o bin/run cmd/run/main.go
```

### 运行

```bash
# 运行 server
./bin/server -config configs/config.yaml

# 运行 api
./bin/api -config configs/config.yaml

# 运行 worker
./bin/worker -config configs/config.yaml

# 运行任务
./bin/run --task=cleanup_logs
```

## 许可证

MIT License