cecb19e497
- 新增 cron模块，支持定时任务管理- 实现了任务列表获取、任务添加、任务移除和任务状态获取等接口 - 添加了默认任务，包括数据同步、数据清理、健康检查和缓存刷新等 - 实现了优雅关闭功能，确保在服务停止时正确停止所有任务 - 添加了定时任务相关文档和使用指南
207 lines
4.3 KiB
Go
207 lines
4.3 KiB
Go
# 定时任务模块使用指南
|
||
|
||
## 概述
|
||
|
||
本项目集成了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界面管理
|
||
- 邮件/短信告警 |