简介

任务队列模块，提供异步任务添加、去重、执行和定时循环功能。任务按队列顺序依次执行（单线程模型），支持超时控制和唯一任务约束（同一 action 在队列中只能存在一次）。适用于后台异步操作、定时轮询等场景。

导入

import "github.com/wallace5303/ee-go/etask"

API

Task

说明：任务结构体，表示队列中的异步任务。

字段	类型	说明
Action	string	任务标识名称，例如 "task.demo"
Handler	reflect.Value	任务处理函数，通过 reflect.ValueOf 包装
Args	[]interface{}	传递给 Handler 的参数列表
Created	time.Time	任务创建时间
Timeout	time.Duration	任务执行超时时长，默认 24 小时

UniqueActions

说明：全局唯一任务 action 列表。对于此列表中的任务 action，队列中只能存在一个实例 — 如果当前队列或正在执行的任务已有相同 action，AddTask / AddTaskWithTimeout 将跳过添加。

类型：[]string

示例：

etask.UniqueActions = []string{"task.syncData", "task.cleanup"}
// 后续添加同名任务时，如果队列中已存在则自动跳过

AddTask(action, handler, args...)

说明：向队列添加任务。默认超时为 24 小时（24 * time.Hour）。如果应用正在退出（eruntime.IsExiting == true），则跳过添加。如果任务 action 属于 UniqueActions 且队列中已存在同名任务，则跳过添加。

参数：

参数	类型	必填	说明
action	string	是	任务标识名称，例如 "task.demo"
handler	interface{}	是	任务处理函数
args	...interface{}	否	传递给 handler 的参数

返回值：无返回值

示例：

etask.AddTask("task.sendEmail", func(to string) {
    fmt.Println("发送邮件给:", to)
}, "user@example.com")

参见：AddTaskWithTimeout — 添加带自定义超时的任务

AddTaskWithTimeout(action, handler, timeout, args...)

说明：向队列添加带自定义超时的任务。超时时任务在日志中标记警告，但不终止 goroutine。其余逻辑与 AddTask 相同。

参数：

参数	类型	必填	说明
action	string	是	任务标识名称
handler	interface{}	是	任务处理函数
timeout	time.Duration	是	任务执行超时时长
args	...interface{}	否	传递给 handler 的参数

返回值：无返回值

示例：

etask.AddTaskWithTimeout("task.longOperation", func() {
    // 耗时操作
}, 5*time.Minute)

Contain(action, moreActions...)

说明：检查队列中是否包含指定 action 的任务。可同时检查多个 action（去重检查），队列中存在任一匹配时返回 true。

参数：

参数	类型	必填	说明
action	string	是	要检查的任务 action
moreActions	...string	否	附加的 action 检查列表

返回值：bool — 队列中存在匹配 action 的任务返回 true，否则返回 false

示例：

if etask.Contain("task.syncData", "task.cleanup") {
    fmt.Println("队列包含 syncData 或 cleanup 任务")
}

Status()

说明：打印当前任务队列状态信息。输出所有待执行任务和当前正在执行任务的 action 列表及数量。仅在开发环境（eruntime.IsDev()）输出到日志。

返回值：无返回值

示例：

etask.Status()
// 开发环境日志输出:
// task status data:  [{"action":"task.syncData"}, {"action":"task.sendEmail"}]

ExecTask()

说明：从队列头部取出一个任务并执行。如果应用正在退出（eruntime.IsExiting == true）或队列为空，则直接返回。执行任务时使用 reflect.Value.Call 调用处理函数，并通过 context.WithTimeout 控制超时。任务完成时记录 "task [action] done"，超时时记录 "task [action] timeout"。执行过程中发生 panic 时由 eutil.Recover() 捕获并记录。

返回值：无返回值

示例：

// 通常在主循环中调用
for {
    etask.ExecTask()
    time.Sleep(100 * time.Millisecond)
}

Every(interval, f)

说明：按指定时间间隔重复执行函数。启动时随机休眠 50~200 毫秒（避免多实例同时启动），然后无限循环：执行函数 → 等待间隔 → 再次执行。函数执行过程中发生的 panic 由 eutil.Recover() 捕获，不会中断循环。

参数：

参数	类型	必填	说明
interval	time.Duration	是	循环间隔时长
f	func()	是	每次循环迭代执行的函数

返回值：无返回值（此函数无限循环，通常在独立 goroutine 中调用）

示例：

// 在独立 goroutine 中启动定时任务
go etask.Every(30*time.Second, func() {
    fmt.Println("健康检查运行中")
})