# task **Repository Path**: gousing/task ## Basic Information - **Project Name**: task - **Description**: 开箱即用的 Gousing Task, 基于分片定时任务队列调度器进行管理，提供全局默认任务管理器, 支持状态监控和管理，支持多种任务类型，包含定时模式/延迟模式/周期模式。 - **Primary Language**: Go - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-03-14 - **Last Updated**: 2025-07-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Gousing Task ### 介绍 开箱即用的 Gousing Task, 基于分片定时任务队列调度器进行管理，提供全局默认任务管理器, 支持状态监控和管理，支持多种任务类型，包含定时模式/延迟模式/周期模式, 支持运行册数限制和超时控制。 > 无依赖，不使用Cron表达式语法，提供直接语义化接口，如： > 定时模式 > - OnceAt 创建一次性定时任务（基于一个明确时间） > 定时模式 > - OnceAfter 创建一次性延迟任务（基于一个延迟时间） > - OnceBuffer 创建一次性延迟任务(缓冲模式), 常用于延迟更新任务, 如缓存更新等场景 > 周期模式 > - EveryInterval 创建周期性任务,基于一个明确的间隔时间 interval > - EverySecond 创建周期性任务（每几秒钟运行一次） > - EveryMinute 创建周期性任务（每几分钟运行一次） > - EveryHour 创建周期性任务（每几小时运行一次） > - EveryDay 创建周期性任务（每几天运行一次） > - EveryWeekDay 创建周期性任务（每周几运行一次） > - EveryMonthDay 创建周期性任务（每月的某一日运行一次） > - EveryMonthFirstDay 创建周期性任务（每月第1天运行一次） > - EveryMonthLastDay 创建周期性任务（每月最后一天运行一次） > 添加任务时，支持更细定时控制和超时控制 > - WithStartAt 设置任务开始的时间(默认为Now) > - WithHour 设置任务时刻：时 (默认为当前小时) > - WithMinute 设置任务时刻：分 (默认为当前分钟) > - WithSecond 设置任务时刻：秒 (默认为当前秒) > - WithMillisecond 设置任务时刻：毫秒 (默认为当前毫秒) > - WithTimeout 设置任务执行超时时间(默认为0, 即不限制) > - WithRunMax 设置任务执行最大次数(周期任务有效, 默认为0, 即不限制) ### 安装 ```golang go get -u gitee.com/gousing/task ``` ### 使用 开箱即用, 全局默认任务管理器 ```golang import "gitee.com/gousing/task" // Global 获取全局默认任务管理器 // task.GetGlobal() *TaskManager // task.SetGlobal(*TaskManager) // OnceAt 创建一次性定时任务（基于一个明确时间） // - executeAt 调度器内部会统一转换为本地时区后处理，如已过期则调整为当前时间(立即执行) // - ops 可通过 TaskOption 指定任务运行的超时时间: WithTimeout // - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务 task.OnceAt(key string, executeAt time.Time, handler TaskHandler, ops ...TaskOption) error // 一小时后运行，超时设置为 1s task.OnceAt("key", time.Now().Add(time.Hour), func() error { return nil }, WithTimeout(time.Second)) // EveryInterval 创建周期性任务,基于一个明确的间隔时间 interval // - ops 可通过 TaskOption 指定具体的具体运行时刻：WithHour WithMinute WithSecond WithMillisecond // - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务 task.EveryInterval(key string, interval time.Duration, handler TaskHandler, ops ...TaskOption) error // 每秒钟运行一次, 一直重复直到任务被删除 task.EveryInterval("key", time.Second, func() error { return nil }) // 每秒钟运行一次, 运行100次 task.EveryInterval("key", time.Second, func() error { return nil }, WithRunMax(100)) // 更多接口见 TaskManagerIO ``` 自定义任务管理器 ```golang import "gitee.com/gousing/task" // NewTaskManager 创建一个新任务管理器 // - name string 管理器名称 // - options *Options 配置选项 // - type Options struct { // - ShardCount int // 任务队列存储分片数量, 默认 32, 最小 1, 最大 512 // - WorkerCount int // 任务处理协程数量, 默认 2048, 最小 1, 最大 262144 // - CheckPeriod time.Duration // 任务队列检查最小时间，决定了定时任务定时/间隔精度， 默认 10 毫秒, 最小 1毫秒, 最大 1000毫秒(1秒) // - } func NewTaskManager(name string, options *Options) *TaskManager myTask := task.NewTaskManager("MyTask",&options{ShardCount:32,WorkerCount：2048,CheckPeriod：10*time.Millisecond}) // OnceAt 创建一次性定时任务（基于一个明确时间） // - executeAt 调度器内部会统一转换为本地时区后处理，如已过期则调整为当前时间(立即执行) // - ops 可通过 TaskOption 指定任务运行的超时时间: WithTimeout // - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务 myTask.OnceAt(key string, executeAt time.Time, handler TaskHandler, ops ...TaskOption) error // 更多接口见 TaskManagerIO ``` ### TaskManagerIO 注意：如未设置超时时间, 默认任务执行超时时间为30秒 ```golang // OnceAt 创建一次性定时任务（基于一个明确时间） // - executeAt 调度器内部会统一转换为本地时区后处理，如已过期则调整为当前时间(立即执行) // - ops 可通过 TaskOption 指定任务运行的超时时间: WithTimeout // - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务 OnceAt(key string, executeAt time.Time, handler TaskHandler, ops ...TaskOption) error // OnceAfter 创建一次性延迟任务（基于一个延迟时间） // - ops 可通过 TaskOption 指定任务运行的开始时间: WithStartAt 超时时间: WithTimeout 等 // - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务 OnceAfter(key string, delay time.Duration, handler TaskHandler, ops ...TaskOption) error // OnceBuffer 创建一次性延迟任务(缓冲模式), 常用于延迟更新任务, 如缓存更新等场景 // - ops 可通过 TaskOption 指定任务运行的开始时间: WithStartAt 超时时间: WithTimeout 等 // - 注意：任务添加后/执行前相同Key任务的添加操作将会忽略 OnceBuffer(key string, delay time.Duration, handler TaskHandler, ops ...TaskOption) error // EveryInterval 创建周期性任务,基于一个明确的间隔时间 interval // - ops 可通过 TaskOption 指定具体的具体运行时刻：WithHour WithMinute WithSecond WithMillisecond // - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务 EveryInterval(key string, interval time.Duration, handler TaskHandler, ops ...TaskOption) // EverySecond 创建周期性任务（每几秒钟运行一次） // - ops 可通过 TaskOption 指定具体的具体运行时刻: WithMillisecond // - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务 EverySecond(key string, seconds int, handler TaskHandler, ops ...TaskOption) error // EveryMinute 创建周期性任务（每几分钟运行一次） // - ops 可通过 TaskOption 指定具体的具体运行时刻：WithSecond WithMillisecond // - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务 EveryMinute(key string, minutes int, handler TaskHandler, ops ...TaskOption) error // EveryHour 创建周期性任务（每几小时运行一次） // - ops 可通过 TaskOption 指定具体的具体运行时刻：WithMinute WithSecond WithMillisecond // - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务 EveryHour(key string, hours int, handler TaskHandler, ops ...TaskOption) error // EveryDay 创建周期性任务（每几天运行一次） // - ops 可通过 TaskOption 指定具体的具体运行时刻：WithHour WithMinute WithSecond WithMillisecond // - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务 EveryDay(key string, days int, handler TaskHandler, ops ...TaskOption) error // EveryWeekDay 创建周期性任务（每周X运行一次） // - weekDay 0-7, 0/7 => 星期日 // - ops 可通过 TaskOption 指定具体的具体运行时刻：WithHour WithMinute WithSecond WithMillisecond // - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务 EveryWeekDay(key string, weekDay int, handler TaskHandler, ops ...TaskOption) error // EveryMonthDay 创建周期性任务（每月的某一日运行一次） // - day: 1-31, 如指定31号，但当月只有30天，则30日执行 // - ops 可通过 TaskOption 指定具体的具体运行时刻：WithHour WithMinute WithSecond WithMillisecond // - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务 EveryMonthDay(key string, day int, handler TaskHandler, ops ...TaskOption) error // EveryMonthFirstDay 创建周期性任务（每月第1天运行一次） // - ops 可通过 TaskOption 指定具体的具体运行时刻：WithHour WithMinute WithSecond WithMillisecond // - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务 EveryMonthFirstDay(key string, handler TaskHandler, ops ...TaskOption) error // EveryMonthLastDay 创建周期性任务（每月最后一天运行一次） // - ops 可通过 TaskOption 指定具体的具体运行时刻：WithHour WithMinute WithSecond WithMillisecond // - 注意：任务添加后/执行前相同Key任务的添加操作会直接覆盖前一次添加的任务 EveryMonthLastDay(key string, handler TaskHandler, ops ...TaskOption) error // Remove 删除指定key的任务 RemoveTask(keys ...string) error // RemoveAllTasks 删除所有任务 RemoveAllTasks() error // GetTask 获取指定key的定时任务 GetTask(key string) (TaskInfo, error) // GetAllTasks 获取所有定时任务信息 GetAllTasks() ([]TaskInfo, error) // Size 获取定时任务数量(包含未运行、已运行的全部任务) // - 包含全部定时任务的映射(可主动通过RemoveTask删除指定任务信息) Size() int // IsRuning 获取定时任务管理器运行状态 IsRuning() bool // Monitor 获取定时任务运行监控信息 Monitor() TaskMonitorData // Stop 关闭定时任务管理器 // - 注意：仅停止定时任务管理器的运行，不会删除任务数据 Stop() error // Restart 重启定时任务管理器 // - 注意：重启后，所有到期任务会立即运行 Restart() ``` ### Test Benchmark Test 全包测试需要设置下超时，以完成任务执行测试 ```shell go.exe test -timeout 60s -run ^Test* gitee.com/gousing/task -v ``` Benchmark ```shell go.exe test -benchmem -run=^$ -bench ^Benchmark* gitee.com/gousing/task -v goos: windows goarch: amd64 pkg: gitee.com/gousing/task cpu: 12th Gen Intel(R) Core(TM) i5-12400F ``` | Benchmark | - | - | - | - | | :------------------------------------- | :------ | :--------- | :------- | :---------- | | BenchmarkTaskManager_1S_16P | 1000000 | 1164 ns/op | 524 B/op | 4 allocs/op | | BenchmarkTaskManager_3S_96P | 1000000 | 1129 ns/op | 462 B/op | 4 allocs/op | | BenchmarkTaskManager_32S_2048P_Default | 1000000 | 1153 ns/op | 521 B/op | 4 allocs/op | | BenchmarkTaskManager_64S_4096P | 1000000 | 1213 ns/op | 517 B/op | 4 allocs/op | ### Gousing 通用选项 #### 自定义 Logger ```golang // 默认使用Golang标准库slog.Default()全局日志记录日志 // task.SetLogger(*slog.Logger) myLogger := slog.New(slog.NewJSONHandler(os.Stdout, nil)) task.SetLogger(myLogger) ```