# 快速開始

本頁說明如何安裝 go-scheduler、建立排程器、註冊第一個任務並優雅關閉。

## 前置需求

- Go 1.23 或以上版本
- 非 Windows 平台：`core.New` 依賴 `log/syslog`，syslog 無法連線時改寫 stderr

## 安裝

### 使用 go get

```bash
go get github.com/pardnchiu/go-scheduler@latest
```

套件位於 `core` 子目錄：

```go
import "github.com/pardnchiu/go-scheduler/core"
```

### 從原始碼

```bash
git clone https://github.com/pardnchiu/go-scheduler.git
cd go-scheduler
go build ./...
go test -race ./...
```

## 第一個任務

```go
package main

import (
	"context"
	"log"
	"os/signal"
	"syscall"

	"github.com/pardnchiu/go-scheduler/core"
)

func main() {
	c, err := core.New(core.Config{})
	if err != nil {
		log.Fatal(err)
	}

	id, err := c.Add("@every 30s", func() {
		log.Println("heartbeat")
	}, "heartbeat")
	if err != nil {
		log.Fatal(err)
	}
	log.Println("task id:", id)

	c.Start()

	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
	defer stop()
	<-ctx.Done()

	// 等待進行中任務結束
	<-c.Stop().Done()
}
```

| 步驟 | 呼叫 | 結果 |
|---|---|---|
| 1 | `core.New(core.Config{})` | 建立排程器，時區為 `time.Local` |
| 2 | `c.Add("@every 30s", ...)` | 註冊任務並回傳遞增 ID；`@every` 最小間隔 30 秒 |
| 3 | `c.Start()` | 計算各任務下次觸發時間並啟動事件迴圈 |
| 4 | `c.Stop().Done()` | 停止排程，進行中任務結束後 context 被 cancel |

## go-scheduler 的定位

go-scheduler 是行程內（in-process）函式庫：匯入 `core`、在自己的 Go 程式中註冊任務，每個 action 都在該行程的 goroutine 中執行，不需要另外部署伺服器。

| 專案 | 型態 | 說明 |
|---|---|---|
| robfig/cron | 行程內 Go 函式庫 | Go 的 cron 函式庫 |
| go-co-op/gocron | 行程內 Go 函式庫 | 流暢 API 風格的 Go cron 排程 |
| reugn/go-quartz | 行程內 Go 函式庫 | 極簡、零依賴的排程函式庫 |
| adhocore/gronx | Go 函式庫與獨立 daemon | Cron 表達式解析器，並提供 task runner、job scheduler 與 daemon |
| madflojo/tasks | 行程內 Go 函式庫 | 週期性任務的行程內排程器 |
| ouqiang/gocron | 自架服務 | 具 Web 管理介面的排程管理系統，由獨立的任務節點執行 shell 與 HTTP 任務 |
| labulakalia/crocodile | 自架服務 | 分散式任務排程系統，由調度中心透過 gRPC 呼叫 Worker 節點 |

在行程內函式庫這一類中，go-scheduler 把所有選項集中在一次 `Add` 呼叫：五欄位 Cron 表達式、描述符或 `@every` 間隔；以 `[]core.Wait` 宣告前置任務，並對每個前置任務指定 `Stop` 或 `Skip` 策略；以及執行時限與逾時回呼。`Stop` 回傳的 context 會在無依賴的進行中任務結束後 cancel。

## 下一步

- [任務模型](/zh/core-concepts) — 任務欄位與狀態
- [排程語法](/zh/core-concepts-schedule) — Cron 欄位、描述符與 `@every`
- [設定](/zh/configuration) — 時區與單一任務選項
- [架構](/zh/architecture) — 事件迴圈、最小堆與 Worker 池
- [排程器 API](/zh/api-reference) — 完整簽章與錯誤條件