Help us shape the future of Go! Take the 2026 Go Developer Survey

job

package
v2.0.3 Latest Latest
Warning

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

Go to latest
Published: Sep 7, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// ScheduleCron cron 表达式调度,ScheduleConf 为 cron 表达式。
	// 支持 5 段(分 时 日 月 周)、6 段(秒 分 时 日 月 周)以及 @every 5m / @daily 等描述符
	ScheduleCron = "cron"
	// ScheduleFixedRate 固定频率调度,ScheduleConf 为间隔秒数,从上次「开始执行」时刻起算
	ScheduleFixedRate = "fixed_rate"
	// ScheduleFixedDelay 固定延迟调度,ScheduleConf 为间隔秒数,从上次「执行结束」时刻起算
	ScheduleFixedDelay = "fixed_delay"
	// ScheduleOnce 一次性调度,ScheduleConf 为执行时间(2006-01-02 15:04:05),执行后自动停止
	ScheduleOnce = "once"
)

调度类型

View Source
const (
	// BlockSerial 串行排队:等待上一次执行完成后依次执行
	BlockSerial = "serial"
	// BlockDiscard 丢弃后续:上次仍在执行则直接丢弃本次调度
	BlockDiscard = "discard"
	// BlockConcurrent 并发执行:不做任何限制,允许多实例同时执行
	BlockConcurrent = "concurrent"
	// BlockCover 覆盖之前:取消正在执行的任务(触发其 context 取消),立即执行本次
	BlockCover = "cover"
)

阻塞处理策略:上一次调度尚未执行完毕时,本次调度的处理方式

View Source
const (
	// MisfireDoNothing 忽略错过的调度,等待下一个调度时刻
	MisfireDoNothing = "do_nothing"
	// MisfireFireNow 立即补偿执行一次
	MisfireFireNow = "fire_now"
)

调度过期策略:服务停机等原因导致错过了调度时刻

View Source
const (
	// StatusStopped 已停止
	StatusStopped = 0
	// StatusRunning 运行中
	StatusRunning = 1
)

任务状态

View Source
const (
	// TriggerCron 调度器自动触发
	TriggerCron = "cron"
	// TriggerManual 人工手动触发
	TriggerManual = "manual"
	// TriggerRetry 失败重试触发
	TriggerRetry = "retry"
	// TriggerMisfire 调度过期补偿触发
	TriggerMisfire = "misfire"
)

触发类型

View Source
const (
	// LogRunning 执行中
	LogRunning = 0
	// LogSuccess 执行成功
	LogSuccess = 1
	// LogFailed 执行失败
	LogFailed = 2
	// LogTimeout 执行超时
	LogTimeout = 3
	// LogBlocked 因阻塞策略被丢弃
	LogBlocked = 4
	// LogCanceled 被覆盖策略取消
	LogCanceled = 5
)

执行结果状态

View Source
const (
	DriverMysql  = "mysql"
	DriverSqlite = "sqlite"
)

支持的存储驱动

Variables

This section is empty.

Functions

func ListHandlers

func ListHandlers() []string

ListHandlers 返回所有已注册的执行器名称(升序)

func Register

func Register(name string, h HandlerFunc)

Register 注册一个定时任务执行器。 name 需与数据库任务表中的 handler_name 一致,重复注册会覆盖并打印警告。 建议在 app 启动、Job 模块 Start 之前完成所有执行器注册。

job.Register("syncUserJob", func(ctx *job.Context) error {
    ctx.Log("开始同步用户, 参数=%s", ctx.Param)
    return userService.Sync(ctx.Ctx())
})

func RouterGroup

func RouterGroup(g *gin.RouterGroup)

RouterGroup 返回可挂载到任意 Gin 路由组下的定时任务管理接口。

提供的接口(以 group 的前缀为 /job 为例):

GET    /job/list          任务列表(分页,支持 group/keyword/status 过滤)
GET    /job/:id           任务详情
POST   /job               新增任务
PUT    /job               更新任务
DELETE /job/:id           删除任务
POST   /job/:id/start     启动任务
POST   /job/:id/stop      停止任务
POST   /job/:id/trigger   手动触发一次
GET    /job/handlers      已注册执行器列表
GET    /job/log           执行日志列表(分页)

用法:

job.GetManager()            // 确保已初始化
r := router.Group("/job")
job.RouterGroup(r)

func Start

func Start() error

Start 启动定时任务调度器。 会依次完成:加载配置 → 选择数据库 → 自动建表 → 载入任务 → 启动调度/同步/清理协程。 应在所有 job.Register 执行器注册完成之后调用。

func Stop

func Stop()

Stop 停止调度器并等待正在执行的任务结束

func Unregister

func Unregister(name string)

Unregister 注销执行器

Types

type Config

type Config struct {
	// Enabled 是否启用定时任务模块
	Enabled bool
	// DbName 多库(multidb)模式下指定使用的库名,单库模式留空
	DbName string
	// Initdb 是否自动建表(AutoMigrate),默认 true
	Initdb bool
	// TablePrefix 表名前缀,默认 mgin_
	TablePrefix string
	// ScanInterval 调度扫描间隔(秒),默认 1
	ScanInterval int
	// RefreshInterval 从数据库同步任务配置的间隔(秒),默认 30
	RefreshInterval int
	// LogRetainDays 执行日志保留天数,0 表示不清理,默认 30
	LogRetainDays int
	// MaxConcurrent 全局最大并发执行任务数,默认 50
	MaxConcurrent int
	// MaxSerialQueue serial 阻塞策略下的最大排队数,超出则丢弃,默认 10
	MaxSerialQueue int
	// Timezone 调度时区,默认 Local,例如 Asia/Shanghai
	Timezone string
}

Config 定时任务管理器配置,对应 application.yml 中 go.job 节点

type Context

type Context struct {

	// JobId 任务 ID
	JobId int64
	// JobName 任务名称
	JobName string
	// JobGroup 任务分组
	JobGroup string
	// HandlerName 执行器名称
	HandlerName string
	// Param 任务参数,来自任务配置的 JobParam 或手动触发时传入的参数
	Param map[string]interface{}
	// LogId 本次执行的日志 ID
	LogId int64
	// TriggerType 触发类型:cron / manual / retry / misfire
	TriggerType string
	// RetryNum 当前重试次数,0 表示首次执行
	RetryNum int
	// contains filtered or unexported fields
}

Context 定时任务执行上下文,作为参数传递给 HandlerFunc

func (*Context) Ctx

func (c *Context) Ctx() context.Context

Ctx 返回标准库 context,便于传递给下游数据库/HTTP 调用

func (*Context) Deadline

func (c *Context) Deadline() (time.Time, bool)

Deadline 返回上下文截止时间

func (*Context) Done

func (c *Context) Done() <-chan struct{}

Done 返回上下文完成通道,用于感知超时或被取消

func (*Context) Err

func (c *Context) Err() error

Err 返回上下文错误

func (*Context) Log

func (c *Context) Log(format string, args ...any)

Log 记录一行执行明细,最终会写入执行日志表的 log_detail 字段。 支持 fmt 风格的格式化参数。

type HandlerFunc

type HandlerFunc func(ctx *Context) error

HandlerFunc 定时任务执行体。 返回 error 即视为本次执行失败,会按任务配置的重试次数进行重试。 实现中应当监听 ctx.Done() 以支持超时中断与 cover 策略取消。

func GetHandler

func GetHandler(name string) HandlerFunc

GetHandler 获取已注册的执行器,不存在返回 nil

type JobInfo

type JobInfo struct {
	ID          int64  `gorm:"primaryKey;autoIncrement;comment:任务ID" json:"id" form:"id"`
	JobName     string `` /* 136-byte string literal not displayed */
	JobGroup    string `gorm:"column:job_group;size:50;index;default:DEFAULT;comment:任务分组" json:"jobGroup" form:"jobGroup"`
	Description string `gorm:"column:description;size:255;comment:任务描述" json:"description" form:"description"`

	ScheduleType string `` /* 151-byte string literal not displayed */
	ScheduleConf string `` /* 165-byte string literal not displayed */

	HandlerName string                 `` /* 178-byte string literal not displayed */
	JobParam    map[string]interface{} `gorm:"column:job_param;type:text;serializer:json;comment:任务执行参数" json:"jobParam" form:"jobParam"`

	Timeout         int    `gorm:"column:timeout;default:0;comment:执行超时时间(秒),0为不限制" json:"timeout" form:"timeout"`
	RetryCount      int    `gorm:"column:retry_count;default:0;comment:失败重试次数" json:"retryCount" form:"retryCount"`
	RetryInterval   int    `gorm:"column:retry_interval;default:0;comment:失败重试间隔(秒)" json:"retryInterval" form:"retryInterval"`
	BlockStrategy   string `` /* 146-byte string literal not displayed */
	MisfireStrategy string `` /* 150-byte string literal not displayed */

	Status int `gorm:"column:status;default:0;index;comment:任务状态 1运行中 0已停止" json:"status" form:"status"`

	LastFireTime *time.Time `gorm:"column:last_fire_time;comment:上次调度时间" json:"lastFireTime"`
	NextFireTime *time.Time `gorm:"column:next_fire_time;comment:下次调度时间" json:"nextFireTime"`
	TriggerCount int64      `gorm:"column:trigger_count;default:0;comment:累计调度次数" json:"triggerCount"`
	SuccessCount int64      `gorm:"column:success_count;default:0;comment:累计成功次数" json:"successCount"`
	FailCount    int64      `gorm:"column:fail_count;default:0;comment:累计失败次数" json:"failCount"`

	Remark   string    `gorm:"column:remark;size:255;comment:备注" json:"remark" form:"remark"`
	CreateAt time.Time `gorm:"column:create_at;autoCreateTime;comment:创建时间" json:"createAt"`
	UpdateAt time.Time `gorm:"column:update_at;autoUpdateTime;comment:更新时间" json:"updateAt"`
}

JobInfo 定时任务配置表。

注意:本表的字段刻意不使用 MySQL 方言专属类型(如 tinyint / datetime), 全部交由 GORM 按当前数据库方言自动推导,以保证同一套模型可在 MySQL / PostgreSQL / SQLite 三种数据库上正确建表。

func (JobInfo) TableName

func (JobInfo) TableName() string

type JobLog

type JobLog struct {
	ID       int64  `gorm:"primaryKey;autoIncrement;comment:日志ID" json:"id" form:"id"`
	JobId    int64  `gorm:"column:job_id;index;not null;comment:任务ID" json:"jobId" form:"jobId"`
	JobName  string `gorm:"column:job_name;size:100;index;comment:任务名称" json:"jobName" form:"jobName"`
	JobGroup string `gorm:"column:job_group;size:50;index;comment:任务分组" json:"jobGroup" form:"jobGroup"`

	HandlerName string                 `gorm:"column:handler_name;size:100;comment:执行器名称" json:"handlerName"`
	JobParam    map[string]interface{} `gorm:"column:job_param;type:text;serializer:json;comment:本次执行参数" json:"jobParam"`
	TriggerType string                 `gorm:"column:trigger_type;size:20;comment:触发类型 cron|manual|retry|misfire" json:"triggerType"`

	Status   int        `` /* 145-byte string literal not displayed */
	StartAt  time.Time  `gorm:"column:start_at;index;comment:开始执行时间" json:"startAt"`
	EndAt    *time.Time `gorm:"column:end_at;comment:执行结束时间" json:"endAt"`
	CostMs   int64      `gorm:"column:cost_ms;default:0;comment:执行耗时(毫秒)" json:"costMs"`
	RetryNum int        `gorm:"column:retry_num;default:0;comment:当前为第几次重试,0表示首次执行" json:"retryNum"`

	Message   string `gorm:"column:message;type:text;comment:执行结果信息或错误原因" json:"message"`
	LogDetail string `gorm:"column:log_detail;type:text;comment:任务内通过 ctx.Log 输出的执行明细" json:"logDetail"`
	Hostname  string `gorm:"column:hostname;size:100;comment:执行该任务的实例主机名" json:"hostname"`

	CreateAt time.Time `gorm:"column:create_at;autoCreateTime;index;comment:创建时间" json:"createAt"`
}

JobLog 定时任务执行日志表

func (JobLog) TableName

func (JobLog) TableName() string

type Manager

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

Manager 定时任务管理器(类 xxl-job)。

特性:

  • 任务配置与执行日志持久化在当前 GORM 数据库中(MySQL → PostgreSQL → SQLite 优先级自动选择)
  • 支持 cron 表达式、固定频率、固定延迟、一次性四种调度类型
  • 支持超时中断、失败重试、阻塞策略、调度过期补偿
  • 纯单机调度:调度器只在本进程内工作,不做多实例协调

func GetManager

func GetManager() *Manager

GetManager 获取单例定时任务管理器

func (*Manager) Check

func (m *Manager) Check() error

Check 健康检查,供 mgin 定时自检调用

func (*Manager) IsRunning

func (m *Manager) IsRunning() bool

IsRunning 调度器是否运行中

func (*Manager) Start

func (m *Manager) Start() error

Start 启动调度器

func (*Manager) Stop

func (m *Manager) Stop()

Stop 停止调度器,等待运行中的任务执行完毕

func (*Manager) Store

func (m *Manager) Store() *store

Store 返回底层存储,便于业务侧扩展查询

func (*Manager) Trigger

func (m *Manager) Trigger(id int64, param map[string]interface{}) (int64, error)

Trigger 手动触发一次任务执行(等价于管理界面「执行一次」)。 param 可临时覆盖任务配置中的 JobParam,留空则使用任务配置的参数。 返回本次执行产生的日志 ID;若调度器未运行或任务不存在则返回错误。

Jump to

Keyboard shortcuts

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