# go-cron

**Repository Path**: jishulang/go-cron

## Basic Information

- **Project Name**: go-cron
- **Description**: golang cron
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-16
- **Last Updated**: 2025-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 一、`Entries()` 快照

`Entries()` 快照功能在任务调度器（如 `cron`）中非常有用，它允许你**实时查看当前正在运行的任务列表**。你可以把它理解为一个“任务监控窗口”，让你知道调度器内部当前有哪些任务、它们的下一次执行时间、上一次执行时间、调度规则等。

------

## 🧾 `Entries()` 的作用详解

### 1. **实时查看调度器中的任务**

你可以通过 `Entries()` 方法获取当前调度器中**所有已添加但尚未被移除或完成的任务列表**，这在调试、监控或日志记录时非常有用。

比如你可以这样用：

```go
for _, entry := range cron.Entries() {
    fmt.Printf("任务名: %s, 下次执行时间: %s, 上次执行时间: %s\n",
        entry.Name, entry.NextRun, entry.PrevRun)
}
```

输出示例：

```shell
任务名: daily-job, 下次执行时间: 2025-07-19 10:00:00, 上次执行时间: 2025-07-18 10:00:00
任务名: every-5-seconds, 下次执行时间: 2025-07-18 23:15:30, 上次执行时间: 2025-07-18 23:15:25
```

------

### 2. **用于健康检查或监控系统**

在一些服务中，你可能希望暴露一个 HTTP 接口或 Prometheus 指标来监控当前运行的任务情况。`Entries()` 提供了结构化的数据，可以方便地集成到这些系统中。

例如：

- 监控任务是否被正确添加
- 检查某个任务是否卡住或长时间未执行
- 统计任务数量、下次执行时间分布等

------

### 3. **调试和日志记录**

在开发阶段或运行时遇到问题时，你可以通过 `Entries()` 快照来：

- 确认任务是否真的被添加进调度器
- 查看任务的下一次执行时间是否正确
- 验证任务是否被正确移除

------

### 4. **防止重复添加任务**

你可以在添加任务前调用 `Entries()`，检查某个任务是否已经存在，从而避免重复添加：

```go
exists := false
for _, entry := range cron.Entries() {
    if entry.Name == "my-task" {
        exists = true
        break
    }
}
if !exists {
    cron.Schedule("my-task", myJob, DailyAt(10, 0, 0))
}
```

------

### 5. **用于 UI 展示**

如果你开发了一个带有 Web 界面的任务管理系统，`Entries()` 可以作为后端接口的数据源，将任务信息展示在前端页面上。

------

## 🧱 `Entries()` 的数据结构设计

你当前的 `Entry` 结构如下：

```go
type Entry struct {
	Name     string
	NextRun  time.Time
	PrevRun  time.Time
	Schedule Schedule
}
```

| 字段       | 说明                                         |
| ---------- | -------------------------------------------- |
| `Name`     | 任务的唯一标识名                             |
| `NextRun`  | 下一次执行时间                               |
| `PrevRun`  | 上一次执行时间（如果没有执行过，可能是零值） |
| `Schedule` | 调度规则（如每天、每小时、每周等）           |

你还可以扩展这个结构体，例如：

```go
type Entry struct {
	Name        string
	NextRun     time.Time
	PrevRun     time.Time
	Schedule    Schedule
	LastStatus  string  // 成功、失败、panic 等
	LastErrMsg  string  // 上次错误信息
	CreatedAt   time.Time // 任务添加时间
}
```

------

## 🧪 单元测试中如何使用 `Entries()`

在测试中，你可以使用 `Entries()` 来验证：

- 添加的任务是否真的存在
- 任务的下一次执行时间是否正确
- 移除任务后是否真的从列表中消失

示例测试代码：

```go
func TestEntries(t *testing.T) {
	c := cron.New()
	c.EverySecond("test-job", func() {}, 5)
	c.Start()

	// 等待任务被调度
	time.Sleep(100 * time.Millisecond)

	entries := c.Entries()
	if len(entries) != 1 || entries[0].Name != "test-job" {
		t.Errorf("Expected one job 'test-job' in entries")
	}
}
```

------

## ✅ 总结

| 功能                 | 说明                                     |
| -------------------- | ---------------------------------------- |
| **实时查看任务列表** | 查看当前调度器中所有任务                 |
| **调试与日志**       | 方便排查任务是否被添加、执行时间是否正确 |
| **健康检查**         | 可集成到监控系统中                       |
| **防重复添加任务**   | 避免任务被多次添加                       |
| **UI 展示**          | 可用于可视化任务管理系统                 |

------

如果你希望我帮你：

- 增加任务状态追踪（成功/失败/panic）
- 支持任务执行日志记录
- 增加 `Entries()` 的并发安全优化
- 把 `Entries()` 接入 HTTP 接口或 Prometheus 指标



## 二、时区







| 功能                   | 是否支持 | 说明 |
| ---------------------- | -------- | ---- |
| Start/Stop             | ✅ 已支持 |      |
| Run() 阻塞启动         | ✅ 新增   |      |
| Entries 快照           | ✅ 新增   |      |
| 启动前添加任务         | ✅ 新增   |      |
| 启动后添加任务         | ✅ 支持   |      |
| 任务移除               | ✅ 支持   |      |
| 多任务并发             | ✅ 支持   |      |
| 每天/每周/每月定时任务 | ✅ 支持   |      |
| Panic 恢复             | ✅ 支持   |      |











1. **Cron表达式支持**：支持标准的Unix cron表达式来定义任务的执行时间，包括分钟、小时、日、月、星期几等。
2. **灵活的时间表**：除了基本的cron表达式外，还支持更灵活的任务调度方式，比如指定特定日期和时间执行一次性的任务。
3. **并发控制**：可以配置是否允许某个任务的多个实例并发运行。例如，如果一个任务在上次执行完成之前又被触发了，你可以选择让新旧任务同时执行或阻止新任务开始直到前一个执行完毕。
4. **错误处理**：提供了钩子函数（如OnError）用于处理任务执行过程中出现的错误。
5. **时区支持**：允许为每个任务指定特定的时区，使得任务可以在全球不同的时区按照本地时间进行调度。
6. **健康检查**：提供了一种机制来检查调度器的状态，确保所有的计划任务都在正常运行。
7. **简单易用的API**：拥有简洁直观的API，易于集成到你的Go项目中。只需几行代码就可以添加新的定时任务。
8. **持久化选项**：虽然默认情况下不提供任务持久化，但可以通过扩展实现自己的持久化逻辑，以防止服务器重启后丢失未执行的任务。
9. **多任务调度**：能够同时管理并调度多个不同时间间隔的任务。