taskkit

package module
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 6, 2026 License: Apache-2.0 Imports: 17 Imported by: 1

README

taskkit

taskkit 是基于 gocron v2 的 Go 任务基础类库,提供自动启动的动态任务管理器、任务级 Context、统一日志和 panic 恢复,以及泛型受控并发执行器。

环境要求

  • Go 1.27 或更高版本

安装

go get github.com/go-sdk/taskkit

定时任务

manager, err := taskkit.NewManager(taskkit.WithLocation(time.Local))
if err != nil {
	return err
}

_, err = manager.Add(
	"certificate-renewal",
	taskkit.Cron("0 */6 * * *"),
	func(ctx *taskkit.Context) error {
		logx.Ctx(ctx).Info().Str("run_id", ctx.RunID()).Msg("renew certificates")
		return renew(ctx)
	},
	taskkit.WithName("证书续期"),
	taskkit.WithTags("certificate", "maintenance"),
	taskkit.WithSingleton(),
	taskkit.WithTimeout(30*time.Minute),
)
if err != nil {
	return err
}

NewManager 返回前已经启动调度器,之后新增或更新的任务立即生效。Manager 自动注册到 core/lifex,正常使用 lifex.Wait 的程序不需要单独关闭;独立使用时也可以显式调用 Shutdown。

gocron 调度器自身的内部日志默认关闭。需要排查调度器问题时,可以在创建 Manager 前将 TASKKIT_GOCRON_LOG 设置为 1、t、true、y、yes 或 on(忽略大小写),将内部日志接入 core/logx。该开关不影响任务开始、完成、失败、panic 和分布式锁失败日志。

支持三类调度:

taskkit.Cron("0 2 * * *")
taskkit.CronWithSeconds("*/10 * * * * *")
taskkit.Every(5 * time.Minute)
taskkit.Once(time.Now().Add(time.Hour))

Every 默认按计划开始时间计算下一次运行。需要保证两次执行之间保留完整间隔时,增加 WithIntervalFromCompletion()。

Once 执行后仍保留在 Manager 的状态表中,NextRunAt 变为空;调用方可以查询最后结果、更新为新调度或显式移除。

动态管理

job, ok := manager.Get("certificate-renewal")
jobs := manager.List()

err = manager.Run("certificate-renewal") // 只等待执行请求被调度
err = manager.Update("certificate-renewal", taskkit.Every(time.Hour), renewTask)
err = manager.Remove("certificate-renewal")

err = manager.Pause(ctx)
err = manager.Resume()
err = manager.Shutdown(ctx)

业务 ID 在一个 Manager 内唯一,同时固定作为 gocron job name 和分布式锁键。展示名称不会影响锁身份。

受控并发

err := taskkit.Parallel(
	ctx,
	ids,
	func(ctx context.Context, id string) error {
		return process(ctx, id)
	},
	taskkit.WithLimit(10),
	taskkit.WithItemTimeout(time.Minute),
)

默认会处理全部元素并按输入下标聚合错误。WithFailFast() 会在首个错误后停止派发新元素,并通过 Context 通知已经运行的元素退出。

Redis 多副本锁

Redis 支持位于可选子包:

import taskrdx "github.com/go-sdk/taskkit/locker/rdx"

locker, err := taskrdx.New(redisClient, taskrdx.Config{
	KeyPrefix: "certops:tasks:",
	Expiry: 30 * time.Second,
	AutoExtendEvery: 10 * time.Second,
})
if err != nil {
	return err
}

manager, err := taskkit.NewManager(taskkit.WithLocker(locker))

锁租约不等同于 exactly-once。涉及不可重复副作用时,业务仍需使用幂等键、唯一约束、条件更新或 fencing token 拒绝过期执行者。

Documentation

Overview

Package taskkit 提供自动启动的任务调度、任务执行上下文和受控并发执行能力。

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrManagerClosed 表示任务管理器已经永久关闭。
	ErrManagerClosed = errx.New("task manager is closed")
	// ErrManagerPaused 表示任务管理器当前暂停调度。
	ErrManagerPaused = errx.New("task manager is paused")
	// ErrContextRequired 表示没有提供标准 Context。
	ErrContextRequired = errx.New("context must not be nil")
	// ErrJobIDRequired 表示任务业务标识为空。
	ErrJobIDRequired = errx.New("job id must not be empty")
	// ErrJobNotFound 表示指定任务不存在。
	ErrJobNotFound = errx.New("job not found")
	// ErrJobAlreadyExists 表示任务业务标识已经注册。
	ErrJobAlreadyExists = errx.New("job already exists")
	// ErrScheduleRequired 表示没有提供任务调度规则。
	ErrScheduleRequired = errx.New("job schedule must not be nil")
	// ErrTaskRequired 表示没有提供任务执行函数。
	ErrTaskRequired = errx.New("job task must not be nil")
	// ErrInvalidTimeout 表示超时时间不是正数。
	ErrInvalidTimeout = errx.New("timeout must be greater than zero")
	// ErrInvalidParallelLimit 表示并发上限不是正数。
	ErrInvalidParallelLimit = errx.New("parallel limit must be greater than zero")
	// ErrPanicRecovered 表示任务执行期间发生的 panic 已被恢复。
	ErrPanicRecovered = errx.New("task panic recovered")
)

Functions

func Parallel

func Parallel[T any](ctx context.Context, items []T, fn func(context.Context, T) error, options ...ParallelOption) error

Parallel 使用固定数量的 worker 并发处理全部元素。

Types

type Context

type Context struct {
	context.Context
	// contains filtered or unexported fields
}

Context 在标准 context.Context 上提供当前任务执行的只读元数据。

func FromContext

func FromContext(ctx context.Context) *Context

FromContext 返回当前 context 中的任务执行元数据视图。

func (*Context) JobID

func (c *Context) JobID() string

JobID 返回当前任务稳定的业务标识。

func (*Context) JobName

func (c *Context) JobName() string

JobName 返回当前任务的展示名称。

func (*Context) RunID

func (c *Context) RunID() string

RunID 返回本次执行的唯一标识。

func (*Context) StartedAt

func (c *Context) StartedAt() time.Time

StartedAt 返回本次执行实际开始的时间。

func (*Context) Tags

func (c *Context) Tags() []string

Tags 返回当前任务标签的副本。

type ItemError

type ItemError struct {
	Index int
	Err   error
}

ItemError 记录 Parallel 中失败元素的输入下标。

func (*ItemError) Error

func (e *ItemError) Error() string

func (*ItemError) Unwrap

func (e *ItemError) Unwrap() error

type Job

type Job struct {
	ID       string
	Name     string
	Tags     []string
	Schedule Schedule
	Status   JobStatus
}

Job 是 Manager 中任务定义和运行状态的只读快照。

type JobOption

type JobOption func(*jobConfig) error

JobOption 调整单个任务的执行配置。

func WithIntervalFromCompletion

func WithIntervalFromCompletion() JobOption

WithIntervalFromCompletion 使 Every 从上一次执行完成时间计算下一次运行时间。

func WithName

func WithName(name string) JobOption

WithName 设置任务的展示名称;分布式锁始终使用稳定的业务 ID。

func WithSingleton

func WithSingleton() JobOption

WithSingleton 跳过同一任务上一次执行尚未结束时产生的新调度。

func WithTags

func WithTags(tags ...string) JobOption

WithTags 设置用于分类和查询的任务标签。

func WithTimeout

func WithTimeout(timeout time.Duration) JobOption

WithTimeout 设置每次任务执行的最长时间。

type JobStatus

type JobStatus struct {
	Running         int
	LastResult      Result
	LastStartedAt   time.Time
	LastCompletedAt time.Time
	NextRunAt       time.Time
}

JobStatus 是任务当前运行状态的只读快照。

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

Manager 集中管理进程内的任务定义、调度和运行状态。

func NewManager

func NewManager(options ...ManagerOption) (*Manager, error)

NewManager 创建并立即启动任务管理器,同时登记进程解构函数。

func (*Manager) Add

func (m *Manager) Add(id string, schedule Schedule, task Task, options ...JobOption) (*Job, error)

Add 注册任务;Manager 已启动时会立即应用调度规则。

func (*Manager) Get

func (m *Manager) Get(id string) (*Job, bool)

Get 返回指定任务当前状态的只读快照。

func (*Manager) List

func (m *Manager) List() []*Job

List 返回按业务 ID 排序的全部任务状态快照。

func (*Manager) Pause

func (m *Manager) Pause(ctx context.Context) error

Pause 暂停全部调度并等待正在执行的任务退出。

func (*Manager) Remove

func (m *Manager) Remove(id string) error

Remove 移除任务并取消该任务正在使用的 Context。

func (*Manager) Resume

func (m *Manager) Resume() error

Resume 恢复已经暂停的任务调度。

func (*Manager) Run

func (m *Manager) Run(id string) error

Run 提交一次立即执行请求,不等待任务执行完成。

func (*Manager) Shutdown

func (m *Manager) Shutdown(ctx context.Context) error

Shutdown 永久关闭 Manager,并在 ctx 到期前等待正在执行的任务退出。

func (*Manager) Update

func (m *Manager) Update(id string, schedule Schedule, task Task, options ...JobOption) (*Job, error)

Update 原位替换现有任务的调度和执行配置,底层任务标识保持不变。

type ManagerOption

type ManagerOption func(*managerConfig) error

ManagerOption 调整 Manager 的公共配置。

func WithBaseContext

func WithBaseContext(ctx context.Context) ManagerOption

WithBaseContext 设置所有任务的根 Context;取消该 Context 会停止后续调度。

func WithLocation

func WithLocation(location *time.Location) ManagerOption

WithLocation 设置 Cron 和固定时间任务使用的时区。

func WithLocker

func WithLocker(locker gocron.Locker) ManagerOption

WithLocker 设置多副本任务执行使用的分布式锁。

func WithShutdownTimeout

func WithShutdownTimeout(timeout time.Duration) ManagerOption

WithShutdownTimeout 设置生命周期自动关闭时等待任务退出的最长时间。

type PanicError

type PanicError struct {
	Value any
	Stack []byte
}

PanicError 保存已恢复 panic 的值和调用堆栈。

func (*PanicError) Error

func (e *PanicError) Error() string

func (*PanicError) Unwrap

func (e *PanicError) Unwrap() error

type ParallelOption

type ParallelOption func(*parallelConfig) error

ParallelOption 调整 Parallel 的执行策略。

func WithFailFast

func WithFailFast() ParallelOption

WithFailFast 在首个元素失败后停止派发尚未开始的元素。

func WithItemTimeout

func WithItemTimeout(timeout time.Duration) ParallelOption

WithItemTimeout 设置每个元素单独执行的最长时间。

func WithLimit

func WithLimit(limit int) ParallelOption

WithLimit 设置同时执行的最大元素数量。

type Result

type Result string

Result 表示最近一次任务执行的结果。

const (
	ResultUnknown Result = "unknown"
	ResultSuccess Result = "success"
	ResultFailed  Result = "failed"
	ResultPanic   Result = "panic"
)

type Schedule

type Schedule interface {
	fmt.Stringer
	// contains filtered or unexported methods
}

Schedule 描述任务的调度规则。具体实现由 taskkit 提供。

func Cron

func Cron(expression string) Schedule

Cron 创建使用标准五段表达式的 Cron 调度规则。

func CronWithSeconds

func CronWithSeconds(expression string) Schedule

CronWithSeconds 创建使用六段表达式且包含秒字段的 Cron 调度规则。

func Every

func Every(interval time.Duration) Schedule

Every 创建按固定时间间隔运行的调度规则。

func Once

func Once(at time.Time) Schedule

Once 创建在指定时间运行一次的调度规则。

type Task

type Task func(*Context) error

Task 是由 Manager 调度执行的任务函数。

Directories

Path Synopsis
locker
rdx
Package rdx 提供适配 gocron 的 Redis 分布式任务锁。
Package rdx 提供适配 gocron 的 Redis 分布式任务锁。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL