Files

hu xiaotong cecb19e497 feat(cron): 实现定时任务管理功能

- 新增 cron模块，支持定时任务管理- 实现了任务列表获取、任务添加、任务移除和任务状态获取等接口
- 添加了默认任务，包括数据同步、数据清理、健康检查和缓存刷新等
- 实现了优雅关闭功能，确保在服务停止时正确停止所有任务
- 添加了定时任务相关文档和使用指南

2025-06-23 15:19:38 +08:00

4.3 KiB

Raw Blame History

定时任务模块使用指南

概述

本项目集成了GoFrame的gcron模块，提供了完整的定时任务管理功能。定时任务会在项目启动时自动启动，并在项目关闭时优雅停止。

功能特性

✅ 自动启动和停止定时任务
✅ 支持Cron表达式配置
✅ 任务执行日志记录
✅ 优雅关闭支持
✅ RESTful API管理接口
✅ 配置文件管理
✅ 任务状态监控

默认任务

项目启动时会自动注册以下默认任务：

1. 数据同步任务 (data_sync_hourly)

执行频率: 每小时执行一次
Cron表达式: 0 * * * *
功能: 从第三方网站同步数据到数据库

2. 数据清理任务 (data_cleanup_daily)

执行频率: 每天凌晨2点执行
Cron表达式: 0 2 * * *
功能: 清理过期的缓存数据和日志记录

3. 健康检查任务 (health_check)

执行频率: 每5分钟执行一次
Cron表达式: */5 * * * *
功能: 检查系统健康状态

4. 缓存刷新任务 (cache_refresh)

执行频率: 每30分钟执行一次
Cron表达式: */30 * * * *
功能: 刷新系统缓存

API接口

获取任务列表

GET /cron/jobs

添加新任务

POST /cron/jobs
Content-Type: application/json

{
  "name": "custom_job",
  "cron": "0 12 * * *"
}

移除任务

DELETE /cron/jobs/{name}

获取任务状态

GET /cron/jobs/{name}/status

Cron表达式说明

Cron表达式格式：秒分时日月周

常用示例

0 * * * * - 每小时执行
0 0 * * * - 每天零点执行
0 0 0 * * - 每月1号零点执行
0 0 0 * * 0 - 每周日零点执行
*/5 * * * * - 每5分钟执行
0 0 12 * * 1-5 - 工作日中午12点执行

配置文件

定时任务配置位于 manifest/config/cron.yaml：

cron:
  enabled: true
  jobs:
    data_sync_hourly:
      enabled: true
      cron: "0 * * * *"
      description: "每小时从第三方网站同步数据"
  execution:
    max_concurrent: 10
    timeout: 300
    retry_count: 3
    retry_interval: 60

添加自定义任务

1. 在代码中添加任务

// 在 internal/logic/cron/cron.go 的 registerDefaultJobs 方法中添加
if err := l.AddJob(ctx, "my_custom_job", "0 8 * * *", func() {
    // 你的任务逻辑
    l.myCustomTask(ctx)
}); err != nil {
    return err
}

2. 实现任务逻辑

func (l *Logic) myCustomTask(ctx context.Context) {
    g.Log().Info(ctx, "执行自定义任务...")
    
    // 1. 调用第三方API
    // 2. 处理数据
    // 3. 更新数据库
    // 4. 记录日志
}

3. 通过API动态添加

curl -X POST http://localhost:8283/cron/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dynamic_job",
    "cron": "0 9 * * *"
  }'

监控和日志

日志查看

定时任务的执行日志会记录在应用日志中，包含：

任务开始时间
任务执行时长
任务完成状态
错误信息（如果有）

日志示例

2024-01-01 10:00:00 [INFO] Starting job: data_sync_hourly at 2024-01-01 10:00:00
2024-01-01 10:00:05 [INFO] Completed job: data_sync_hourly, duration: 5.2s

最佳实践

1. 任务设计原则

任务应该是幂等的（可重复执行）
避免长时间运行的任务
合理设置超时时间
添加适当的错误处理

2. 性能优化

使用连接池
批量处理数据
合理使用缓存
避免在任务中执行耗时操作

3. 监控建议

定期检查任务执行状态
监控任务执行时间
设置告警机制
保留执行日志

故障排除

常见问题

任务未执行
- 检查Cron表达式是否正确
- 确认任务是否已注册
- 查看应用日志
任务执行失败
- 检查网络连接
- 验证API接口可用性
- 查看错误日志
任务执行超时
- 优化任务逻辑
- 增加超时时间
- 考虑异步处理

调试方法

启用调试日志
使用API接口检查任务状态
查看系统资源使用情况
检查数据库连接状态

扩展功能

后续可以扩展的功能：

任务执行历史记录
任务依赖关系管理
分布式任务调度
任务执行统计
Web界面管理
邮件/短信告警

4.3 KiB Raw Blame History Unescape Escape