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

- 新增 cron模块，支持定时任务管理- 实现了任务列表获取、任务添加、任务移除和任务状态获取等接口 - 添加了默认任务，包括数据同步、数据清理、健康检查和缓存刷新等 - 实现了优雅关闭功能，确保在服务停止时正确停止所有任务 - 添加了定时任务相关文档和使用指南
2025-06-23 15:19:38 +08:00
parent 89a6cdc001
commit cecb19e497
16 changed files with 1571 additions and 7 deletions
--- a/docs/cron.md
+++ b/docs/cron.md
@@ -0,0 +1,207 @@
+# 定时任务模块使用指南
+
+## 概述
+
+本项目集成了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接口
+
+### 获取任务列表
+```http
+GET /cron/jobs
+```
+
+### 添加新任务
+```http
+POST /cron/jobs
+Content-Type: application/json
+
+{
+  "name": "custom_job",
+  "cron": "0 12 * * *"
+}
+```
+
+### 移除任务
+```http
+DELETE /cron/jobs/{name}
+```
+
+### 获取任务状态
+```http
+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`：
+
+```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. 在代码中添加任务
+
+```go
+// 在 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. 实现任务逻辑
+
+```go
+func (l *Logic) myCustomTask(ctx context.Context) {
+    g.Log().Info(ctx, "执行自定义任务...")
+    
+    // 1. 调用第三方API
+    // 2. 处理数据
+    // 3. 更新数据库
+    // 4. 记录日志
+}
+```
+
+### 3. 通过API动态添加
+
+```bash
+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. 监控建议
+- 定期检查任务执行状态
+- 监控任务执行时间
+- 设置告警机制
+- 保留执行日志
+
+## 故障排除
+
+### 常见问题
+
+1. **任务未执行**
+   - 检查Cron表达式是否正确
+   - 确认任务是否已注册
+   - 查看应用日志
+
+2. **任务执行失败**
+   - 检查网络连接
+   - 验证API接口可用性
+   - 查看错误日志
+
+3. **任务执行超时**
+   - 优化任务逻辑
+   - 增加超时时间
+   - 考虑异步处理
+
+### 调试方法
+
+1. 启用调试日志
+2. 使用API接口检查任务状态
+3. 查看系统资源使用情况
+4. 检查数据库连接状态
+
+## 扩展功能
+
+后续可以扩展的功能：
+- 任务执行历史记录
+- 任务依赖关系管理
+- 分布式任务调度
+- 任务执行统计
+- Web界面管理
+- 邮件/短信告警