# 6.11 定时任务

:::tip 概述
定时任务是数据驱动的常驻调度器：任务定义在 goframe_job 表，启动时加载 status=1 任务挂载 gcron，执行目标分双形态（HTTP 调用 / 本地处理器），三种执行策略叠加多实例执行锁，结果落 goframe_job_log。
:::

## 架构总览

```text
启动（cmd.go 延时 2s）→ DaemonInit 加载 goframe_job 中 status=1 的任务
  → 按 cron_expression 挂载 gcron → tick 触发 executeJob
    → 执行目标分派（HTTP 调用 或 本地处理器）→ 结果写 goframe_job_log

职责分层：
  调度基础设施（挂载/摘除/锁/执行/落日志）在 internal/logic 的 job 模块
  任务业务实现在 internal/task 包（单向依赖 task→logic，logic 禁止反向 import task）
  由 internal/cmd 空白导入 internal/task 触发 init 注册
```

## 执行目标双形态（executeJob 读 url 字段分派）

```text
url 为 http:// 或 https:// 开头 → HTTP 调用目标地址：
  params 为空 GET，非空 POST（application/json，超时 30s）
  非 200 或网络错误 → 失败（exception 记录状态与响应前 1000 字符）

url 其余取值 → 本地处理器方法名，从 jobHandlers 注册表查找：
  签名 func(ctx context.Context, params string) (string, error)
  返回摘要写入任务日志 message
  未注册 → 失败"未找到本地任务处理方法"
```

## 执行策略与执行方式

```text
execute_policy（列值）：
  1 立即执行   允许并发：gcron.Add，tick 即启动新执行；不加执行锁
  2 执行一次   单例调度（gcron.AddSingleton），上次未结束跳过本次；叠加执行锁
  3 放弃执行   并发 tick 照常触发，但抢不到执行锁则放弃本次

is_sync（列值）：
  1 同步   在调度协程内执行（阻塞本条目下一 tick 的派发）
  0 异步   go 协程执行（context.Background()）

执行锁 jobTryLock（策略 2/3 叠加）：
  键 job:lock:{id}，utility/cache SET NX（TTL 300s 兜底——实例崩溃未释放自动过期；
  正常路径 defer 立即释放）。多实例部署共享同一把锁（Redis 模式防跨实例并发；
  内存降级时退化单机语义）

cron 表达式：gf gcron 格式，默认 6 段（秒 分 时 日 月 周）；
  # 前缀表示标准 5 段忽略秒（如 "# */5 * * * *" = 每 5 分钟）
```

## 调度流程与状态机

```text
                 Add（固定置0）
                   │
                   ▼
              ┌─────────┐  Status(1) / Resume   ┌─────────┐
              │ 0 未发布 │─────────────────────▶│ 1 运行中 │◀──┐
              └─────────┘                      └────┬────┘   │
                   ▲            Status(2)/Pause       │        │ Resume
                   │            ─────────────────────▶│        │
                   │            摘除调度               ▼        │
                   │                             ┌─────────┐   │
                   │            Status(0)        │ 2 暂停  │───┘
                   │◀─────────────────────────── └─────────┘
                   │  摘除调度
              Delete：软删 + 摘除调度
              运行中 Update：摘除 → 按新 cron 重挂（失败降级置 2 并报 Cron 无效）
              RunOnce：不看状态，异步 force 执行一次（不改状态）
```

## 管理接口（/api/job）

```text
七件套 sys:job:*
  GET  /api/job/runOnce/:id        sys:job:execute   立即执行（异步，未发布也可执行）
  GET  /api/job/pause/:id          sys:job:pause     摘除调度 + status=2
  GET  /api/job/resume/:id         sys:job:resume    重新挂载 + status=1
  POST /api/job/status             sys:job:update    设状态（1→挂载，其他→摘除）
  GET  /api/job/daemonStatus       登录即可           调度器状态（running/jobIds/startTime）

业务钩子：BeforeAdd 固定 status=0；AfterUpdate 运行中先摘除再重挂；
         BeforeDelete 存在性检查 + 摘除调度
字典：job_status / job_execute_policy / job_is_sync（SerializeMaps 驱动 {field}Text）
```

## 本地处理器注册（internal/task）

```text
logic.RegisterJobHandler(name, h)：注册名全局唯一，重复注册进程 panic
注册名与任务记录 url 字段值一一对应（数据驱动查找）

internal/task 包约定：
  每任务一个文件（snake_case），init 中注册
  处理方法签名 func(ctx, params) (string, error)，返回值写任务日志摘要
  由 internal/cmd 空白导入触发加载（不在 HTTP 启动链路内）

内置任务：
  HelloWorld（hello_world.go）  示例，仅打日志（验证调度链路）
  SendSms（send_sms.go）       仅记录执行参数日志（不对接短信通道）
  LogClean（log_clean.go）     日志清理：每日 02:30 分批物理删除三张日志表
    参数 {"retentionDays": n} 可覆盖 job.logRetentionDays（默认 90）
    单批 5000 行循环至不足一批；单表单次任务上限 200000 行（防长事务/runaway）
```

## 新增任务开发步骤

```text
1) internal/task/{任务名}.go 实现 handler：func(ctx, params) (string, error)
2) init() 中 logic.RegisterJobHandler("TaskName", handler)
3) 任务管理页新增记录：url 填 "TaskName"，params 填 JSON，
   cron_expression 填 6 段或 # 5 段，execute_policy/is_sync 按需
4) Status 置为运行中（发布）→ 调度器挂载；观察 job/log 执行日志
5) go build ./... 并重启（init 注册发生在进程加载期）

注意：handler 可复用 base 共享能力（WithTrans/ChunkQuery）与 dao；
     长任务用分批+上限；HTTP 目标任务自带 30s 超时，长任务应改本地处理器
```

## 多实例部署语义

```text
单实例：gcron 各自挂载，正常运行
多实例 + Redis：策略 2/3 经 job:lock:{id} 全局互斥（同一时刻至多一个实例执行）
  ——仍会重复"触发"（各实例各自 tick），未抢到锁的实例直接放弃
多实例 + 内存降级：锁退化单机语义，可能跨实例并发执行——生产 Redis 必须可用
```

排障口径差异：`daemonStatus.running` 是 gcron 全部条目数（含 CleanTemp 等非任务条目）；`server/info` 的 `Scheduler.mounted` 只统计 "job:" 前缀条目。