五段處理鏈路

第一段：HTTP endpoint 接收

Collector 對外提供一個 HTTP POST endpoint（例如 /v1/events），接收 SDK 送來的 JSON body。每個 request 可以是單一事件或批次事件陣列。

Endpoint 的職責只有兩件事：驗證 HTTP 層面的基本條件（Content-Type、body size limit、認證 token），然後把 body 傳給下一段。HTTP 層面的錯誤（413 body too large、401 unauthorized）在這裡回應，不進入後續處理。

自用工具場景下，Go 的 net/http 標準庫提供的 HTTP server 已足夠。一個 http.HandleFunc("/v1/events", handler) 加上 json.NewDecoder(r.Body).Decode(&events) 就完成接收。不需要 framework。

第二段：JSON Schema 驗證

收到的 JSON body 用 JSON Schema 驗證結構正確性 — 必要欄位是否存在、型別是否正確、值是否在合法範圍內。驗證失敗的事件被拒絕並記錄原因，通過的事件進入下一段。

Schema 驗證是 collector 的品質閘門。沒有驗證的 collector 會累積格式不一致的資料，查詢時需要處理各種邊界條件。驗證在寫入前攔截問題，比寫入後清理成本低。

驗證的粒度是事件級 — 批次中的一個事件驗證失敗不影響其他事件。回應中標明哪些事件被接受、哪些被拒絕及原因。

Ingestion 回應格式

回應格式把「接受了幾筆、拒絕了幾筆、拒絕原因」三件事用一套一致的結構表達。SDK 端只需要判斷 status code 就知道怎麼處理 buffer。

 1// 200 OK — 單筆成功或批次全部成功
 2{ "accepted": 1 }
 3
 4// 207 Multi-Status — 批次部分失敗
 5{
 6  "accepted": 1,
 7  "rejected": 1,
 8  "errors": [
 9    { "index": 1, "message": "missing required field: type", "fields": ["type"] }
10  ]
11}
12
13// 400 Bad Request — 單筆失敗或批次全部失敗
14{
15  "error": "schema validation failed",
16  "details": [
17    { "field": "type", "message": "missing required field" }
18  ]
19}
20
21// 503 Service Unavailable — 寫入端暫時不可用
22{ "error": "service temporarily unavailable", "retry_after": 5 }

設計選擇：207 的 errors 陣列用 index 標明失敗事件在原始 batch 中的位置（0-based），SDK 可以用 index 對照原始事件做 debug log。合法事件不因部分失敗而被丟棄 — 部分成功是 batch 收集的核心價值。400 和 207 的差異是「全軍覆沒 vs 部分存活」，SDK 端的處理策略不同：400 直接清 buffer（schema 問題重試也不會過），207 只清成功的部分。

Health endpoint 回應

Health endpoint 回傳 collector 自身的運行狀態，不包含事件內容。用途是 SDK 端確認 collector 可達、監控腳本定期探測。

1// GET /health → 200 OK
2{
3  "status": "ok",
4  "uptime_seconds": 3600,
5  "total_events": 1234,
6  "storage_bytes": 5242880,
7  "version": "0.1.0"
8}

total_events 和 storage_bytes 讓監控腳本判斷 collector 的負載趨勢。version 讓 SDK 確認 collector 版本（schema 不匹配時的第一個 debug 線索）。

第三段：儲存

通過驗證的事件寫入 Storage Backend。Collector 使用可插拔的 Storage interface — day-one 預設用 SQLite（零依賴、嵌入式），分析需求觸發時切換到 PostgreSQL。具體的 backend 選擇和功能分層見 功能分層與 Backend 選擇，可插拔架構見 規模演進。

第四段：查詢

儲存的事件透過 CLI 指令或 HTTP 查詢 endpoint 存取。SQLite backend 下用 SQL 查詢；匯出為 JSONL 格式後也可用 grep + jq 做臨時分析。

查詢設計見 查詢 API 設計。

第五段：Rule engine

Rule engine 在事件寫入後觸發，檢查事件是否匹配預定義的規則。匹配時執行對應的動作（發通知、寫 summary、觸發 webhook）。

Rule engine 設計見 Rule engine 設計。

多獨立 client 併發寫入

上述五段鏈路描述的是單一 request 的路徑。實際運行時，多個 SDK 會同時送事件——以下先描述場景，下方並發寫入策略再詳述 collector 如何處理。

常見部署場景中，多個完全獨立的 SDK 實例同時送事件到同一個 collector——不同 process、不同 app、甚至不同語言的 SDK。這和「一個 app 內的多 thread 併發」不同：每個 SDK 有自己的 buffer 和 HTTP 連線，不共享任何狀態。

SDK 端不需要知道其他 SDK 的存在。每個 SDK 獨立 init、獨立 buffer、獨立 flush、獨立 close。SDK 端的唯一接觸點是 collector 的 HTTP endpoint——併發安全由 storage backend 的併發策略保證（見下方並發寫入策略），不需要 SDK 端協調。多 client 同時 flush 時的背壓機制見 Ingestion 背壓與流量管控。

例如 CI pipeline 的多個 job 同時送 build 事件，或微服務架構中多個 service 各自送事件到同一個 collector。另一個具體案例是 Claude Code 的 Hook 系統——多個 Hook 同時觸發時，每個 Hook 是獨立的 Python process，各自初始化 SDK、產生事件、flush 到同一個 collector。

並發寫入策略

Go 的 HTTP server 為每個 request 分配一個 goroutine。多個 SDK 同時 flush 時，collector 同時收到多個寫入請求。Storage Backend 的並發能力決定了這些 goroutine 怎麼協調。

SQLite Backend：單寫者模型

SQLite 的 WAL mode 允許一個 writer 和多個 concurrent reader — 讀寫不互相阻塞，但多個 writer 之間是序列化的。Go 端有兩種處理 pattern：

Single-writer goroutine + channel：所有 Store() 呼叫把事件送進一個 Go channel，由一個專屬的 goroutine 從 channel 讀取並序列寫入 SQLite。HTTP handler 送完 channel 後等待確認（或用 buffered channel 異步）。優點是背壓控制清晰 — channel 滿時 HTTP handler 自然阻塞，可以回 503。缺點是多一層間接。

Busy timeout fallback：不在 Go 層管序列化，讓 SQLite driver 自己處理。設定 _pragma=busy_timeout(5000)，多個 goroutine 同時呼叫 Store() 時，SQLite 讓等待的 goroutine block 直到寫入鎖釋放（最多 5 秒）。優點是實作簡單（不需要 channel 和額外 goroutine）。缺點是背壓不可控 — goroutine 數量可能累積。

自用工具場景推薦 busy timeout（簡單）、寫入量增長到出現超時錯誤時切換到 channel pattern。

PostgreSQL Backend：連線池

PostgreSQL 透過連線池（database/sql 的 SetMaxOpenConns）支援並行寫入。多個 goroutine 可以同時寫入不同的連線，不需要額外的序列化機制。

Go 單一 binary 的設計選擇

Collector 用 Go 編譯成單一 binary，不依賴外部 runtime（JVM、Python interpreter、Node.js）。部署是複製一個檔案，啟動是執行一個指令。

這個選擇在自用工具場景下有特定優勢：server 和 collector 在同一台機器上，部署流程是 scp collector user@host: + ssh user@host ./collector。不需要 package manager、不需要 container registry、不需要 orchestration。

Go 的 net/http 標準庫提供 production-ready 的 HTTP server，JSON 處理用標準庫的 encoding/json，SQLite 用 modernc.org/sqlite（pure Go、無 CGO 依賴）。整個 collector 的核心邏輯可以在 500 行以內完成。

具體的部署步驟（systemd service 檔案、啟動參數、設定檔格式）和 Quick Start（從零到第一筆事件出現在 collector）見 monitor repo 的 deployment guide。

下一步路由

• 功能分層與 Backend 選擇 → 功能分層與 Backend 選擇
• 可插拔 Storage Backend 架構 → 規模演進
• JSONL 匯出與備份格式 → JSONL 儲存設計
• 查詢 API 的設計 → 查詢 API 設計
• Rule engine → Rule engine 設計
• 背壓與流量管控的基礎概念 → DevOps 流量管控
• 端到端資料完整性 → 端到端資料完整性
• Error fingerprint 與去重分群 → Error Fingerprint 與去重分群

本章以 scripts/mdtools（blog 自己的 markdown 工具鏈，repo 內檔案）作為 concrete instance。讀者不需要事先熟悉 mdtools — 每段會先講通用 pattern，再用對應 code 示範一種可行實作。

基礎：為什麼需要 flag.NewFlagSet 而非 flag.Parse()

flag.Parse() 只解析一次全域 flag set。對只有一個命令的小工具（如 tool --input foo）夠用；但一旦進入 tool fmt --fix 這種 <tool> <subcommand> [flags] 結構，全域 flag set 就擋路：

• --fix 對 fmt 命令有意義，對 lint 命令沒有。
• 各子命令可能共享 name（例如 --verbose）但預設值或語意不同。
• help 輸出需要分子命令各自列自己的 flags。

flag.NewFlagSet 讓每個子命令擁有獨立的 flag 命名空間：

1fs := flag.NewFlagSet("fmt", flag.ExitOnError)
2fix := fs.Bool("fix", false, "apply fixes in place")
3check := fs.Bool("check", false, "report-only")
4_ = fs.Parse(args) // args = os.Args[2:]，已經跳過了子命令本身

fs.Parse(args) 只看傳進去的片段，不碰 os.Args 全域。這是撐起 subcommand CLI 的核心 API。

專案 Layout：main → cmd/ → internal/

Go 慣例的 CLI 專案結構是三層，對應三種責任：

 1scripts/mdtools/
 2├── main.go             ← 層 1：dispatcher，只做「看第一個參數分派到哪裡」
 3├── cmd/
 4│   ├── fmt.go          ← 層 2：每個子命令一個檔案，負責 flag 解析與呼叫 internal
 5│   ├── lint.go
 6│   ├── cards.go
 7│   └── migrate.go
 8└── internal/
 9    ├── mdfmt/          ← 層 3：純邏輯，不碰 flag、os.Args、os.Exit
10    ├── mdlint/
11    └── mdcards/

分層的目的是支援每層獨立的測試策略：

• layer 1：幾乎不測，因為只是 switch。
• layer 2：integration test（給定 argv、確認 exit code 與 stdout）。
• layer 3：unit test，純函式輸入輸出。後續模組的所有實作技術 — AST 整合、idempotent 改寫、graph 分析 — 都落在這層。

把 os.Exit / os.Args / os.Stderr 都擋在 layer 1-2，layer 3 就能用一般 table-driven test 測，不用起 subprocess。

Layer 1：main.go dispatcher

 1// scripts/mdtools/main.go
 2package main
 3
 4import (
 5	"fmt"
 6	"os"
 7
 8	"blog/scripts/mdtools/cmd"
 9)
10
11func main() {
12	if len(os.Args) < 2 {
13		usage()
14		os.Exit(2)
15	}
16
17	sub := os.Args[1]
18	args := os.Args[2:]
19
20	var exitCode int
21	switch sub {
22	case "fmt":
23		exitCode = cmd.Fmt(args)
24	case "lint":
25		exitCode = cmd.Lint(args)
26	case "cards":
27		exitCode = cmd.Cards(args)
28	case "migrate":
29		exitCode = cmd.Migrate(args)
30	case "-h", "--help", "help":
31		usage()
32	case "version":
33		fmt.Println("mdtools 0.1.0-dev")
34	default:
35		fmt.Fprintf(os.Stderr, "unknown subcommand: %q\n\n", sub)
36		usage()
37		exitCode = 2
38	}
39
40	os.Exit(exitCode)
41}

注意幾個 pattern：

• dispatcher 不做 flag 解析。args := os.Args[2:] 把剩下交給子命令。
• 每個子命令回傳 int，dispatcher 統一呼叫 os.Exit。這讓子命令本身容易測（不會直接 kill 測試 process）。
• -h / --help / help 三種寫法都接受。Unix 慣例。
• unknown subcommand 進 exit code 2，保留 exit 1 給「有違規」的語義。

Layer 2：子命令入口

每個子命令一個檔案，結構類似：

 1// scripts/mdtools/cmd/fmt.go
 2package cmd
 3
 4import (
 5	"flag"
 6	"fmt"
 7	"os"
 8
 9	"blog/scripts/mdtools/internal/files"
10	"blog/scripts/mdtools/internal/mdfmt"
11	"blog/scripts/mdtools/internal/rules"
12)
13
14func Fmt(args []string) int {
15	fs := flag.NewFlagSet("fmt", flag.ExitOnError)
16	fix := fs.Bool("fix", false, "apply fixes in place")
17	check := fs.Bool("check", false, "report-only; non-zero on pending changes")
18	_ = fs.Parse(args)
19
20	if *check && *fix {
21		fmt.Fprintln(os.Stderr, "mdtools fmt: --fix and --check are mutually exclusive")
22		return 2
23	}
24	if !*check && !*fix {
25		*check = true // safe default
26	}
27
28	paths := fs.Args()
29	if len(paths) == 0 {
30		paths = []string{"content"}
31	}
32
33	cfg := rules.Default()
34	mdFiles, err := files.WalkMarkdown(paths)
35	if err != nil {
36		fmt.Fprintf(os.Stderr, "mdtools fmt: walk error: %v\n", err)
37		return 2
38	}
39
40	changed := 0
41	for _, path := range mdFiles {
42		result, err := mdfmt.FormatFile(path, cfg)
43		if err != nil {
44			fmt.Fprintf(os.Stderr, "mdtools fmt: %s: %v\n", path, err)
45			return 2
46		}
47		if !result.Changed() {
48			continue
49		}
50		changed++
51		if *fix {
52			if err := os.WriteFile(path, result.Fixed, 0o644); err != nil {
53				fmt.Fprintf(os.Stderr, "write %s: %v\n", path, err)
54				return 2
55			}
56			fmt.Printf("fixed: %s\n", path)
57		} else {
58			fmt.Printf("would fix: %s\n", path)
59		}
60	}
61
62	if *check && changed > 0 {
63		return 1 // CI-friendly: exit 1 means "things need fixing"
64	}
65	return 0
66}

要注意幾個設計決策：

• flag 定義就在入口函式裡，不抽成 package 常數。每個子命令的 flag 獨立演化。
• ExitOnError 讓 fs.Parse 遇到不合法 flag 直接 exit — 對 CLI 工具 OK，因為 parse 失敗本來就無法繼續。測試時要用 ContinueOnError 避免殺測試。
• positional args 從 fs.Args() 取，不是 os.Args。fs.Parse 會把非 flag 的留在 fs.Args()。
• 預設值走安全側（*check = true when neither given）— 防止使用者意外執行破壞性動作。
• exit code 分層語意：0 = 成功、1 = 有違規、2 = 工具本身失敗。CI script 能用 [[ $? -eq 1 ]] 區分。

Layer 3：internal 實作

Layer 3 是純邏輯，不知道任何 os / flag 的存在。這讓它能被 layer 2 呼叫、被 test 呼叫、也能在未來被其他 binary 或 library 重用：

 1// scripts/mdtools/internal/mdfmt/fixer.go
 2package mdfmt
 3
 4import (
 5	"bytes"
 6	"os"
 7
 8	"blog/scripts/mdtools/internal/rules"
 9)
10
11type FixResult struct {
12	Path     string
13	Original []byte
14	Fixed    []byte
15}
16
17func (r FixResult) Changed() bool {
18	return !bytes.Equal(r.Original, r.Fixed)
19}
20
21func FormatFile(path string, cfg rules.Config) (FixResult, error) {
22	data, err := os.ReadFile(path)
23	if err != nil {
24		return FixResult{}, err
25	}
26	fixed := applyAll(data, cfg)
27	return FixResult{Path: path, Original: data, Fixed: fixed}, nil
28}

FormatFile 回傳 (FixResult, error)，不 os.Exit、不印訊息、不碰全域狀態。Test 可以直接給一個記憶體 []byte 跑 applyAll 驗結果。

什麼時候該上 cobra

升級到 cobra 的判準是stdlib 能處理的負面複雜度已經超過 cobra 的學習成本。下表列五個實際觸發過團隊升級的訊號，每個都附展開說明。

命令層級超過 3 層：kubectl get pods 只有兩層還撐得住；到 gh api repos owner/repo/pulls list --limit 10 就是四層（含 api 這個 namespace），dispatcher 裡巢狀 switch 開始難讀。信號：dispatcher 的 switch case 超過十個，或 case 裡面又呼叫另一個 switch。反例：即使只有兩層，若每層未來會繼續加，早上 cobra 可省後來重構。

需要自動 shell completion：end-user 會反覆打命令、需要 tab 補齊子命令與 flag 名稱時，這功能差很多。手寫 completion 腳本要處理三種 shell 的語法差異，成本高；cobra 一行 cobra.GenBashCompletion 就產生。信號：工具有外部使用者、或團隊已經裝 shell completion。反例：只在 CI 跑、人不會互動輸入。

man-page 形式的 help 輸出：Unix 社群期待工具有 man tool 級的文件。stdlib 只輸出簡單的 usage 字串，排版樸素；cobra 的 doc package 能生成 markdown / reStructuredText / man。信號：工具要 package 進系統（Homebrew、apt），或對外發佈。反例：公司內部用、README 夠用。

多 end-user 讀 help：工程師忍受樸素的 -h 輸出，但產品經理、SRE on-call 看不下。cobra 有明確的 long description、example 欄位，排版比 stdlib 好。信號：使用者包含非程式設計角色。反例：user 是同團隊工程師。

大量共用 flag：--verbose、--log-level、--config 這類 flag 每個子命令都要用。stdlib 要在每個子命令重複 fs.Bool("verbose", ...)；cobra 的 PersistentFlags 能繼承到所有 subcommand。信號：重複 flag 超過三個、或要 enforce 某個 flag 在所有 subcommand 都有。反例：flag 在每個子命令語意不同，共用反而製造混淆。

以上五個訊號在 mdtools 都沒命中（內部工具、單層 subcommand、工程師使用者），所以繼續走 stdlib。若未來 mdtools 對外釋出給讀者下載，就值得重新評估。判讀時機是設計當下，不是感覺「stdlib 開始髒」時 — 髒時通常已經晚。

常見陷阱

在 layer 3 直接呼叫 os.Exit

會破壞 test：test runner 呼叫 TestXxx 時，如果 subject code 裡 os.Exit(1)，整個 test process 退出，其他 test 不跑。Layer 3 應回傳 error，讓 layer 2 決定怎麼退出。

用全域 var fs = flag.NewFlagSet(...) 宣告 flag

每次呼叫會累積狀態（flag 已經被定義過會 panic），並且兩個 test 同時跑會 race。定義 flag 要在函式裡。

忘記 ContinueOnError 就跑 test

ExitOnError 是 production 預設，但測試時會讓測試 process 整個退出。Table-driven test 要用：

1fs := flag.NewFlagSet(name, flag.ContinueOnError)
2fs.SetOutput(io.Discard) // 測試時不要印 usage 到 stderr

太早抽出「所有子命令共用的 flag」

PersistentFlags 概念在 stdlib 沒有，手動在每個子命令重複 fs.Bool("verbose", false, ...) 看似重複但其實可讀。一旦抽成共用 helper，就開始維護一個小框架 — 這時候用 cobra 反而更乾淨。

擴充路徑

• 命令太多時分組：tool fmt check、tool fmt fix 的兩層 subcommand 可以用「每層一個 switch」展開，main → cmd.Fmt → cmd.FmtCheck。mdtools 的 migrate fix-links 就是這個模式（見 cmd/migrate.go）。
• 共用 config loading：rules.Default() 這類邏輯放在 internal 裡，每個子命令呼叫；不要每個子命令自己 parse 配置檔。
• 測試 layer 2：用 buffer 捕獲 stdout/stderr，傳入自定 args。參考 Go stdlib 的 testing/iotest 跟 bytes.Buffer。

下一步

9.2 goldmark AST 入門 會看 mdtools 怎麼把 markdown 解析成可操作的結構，layer 3 內部怎麼組織 parser 整合。

你應該看什麼

• Using Go at Google
• How Google’s Core Data Solutions Team Uses Go
• Go at Google: Language Design in the Service of Software Engineering

這個案例告訴我們什麼

1. Go 很適合大型服務拆分之後的邊界管理。
2. built-in concurrency 對高併發索引與資料處理很重要。
3. Go 的簡單語法與明確依賴，能讓大團隊維持可讀性。

可對照的公開原始碼

• kubernetes/kubernetes

Kubernetes 不是 Google 內部產品，但它很好地呈現了 Google 文化裡常見的 Go 工程模式：大型 codebase、明確 package 邊界、cmd 入口與大量服務協調。

本章目標

學完本章後，你將能夠：

1. 說明 Go 為什麼偏好顯式控制流程
2. 看懂入口程式中依賴組裝的意圖
3. 區分「程式碼短」和「認知負擔低」
4. 用 Go 的風格閱讀現有服務

為什麼這章在第零章

如果工作負載、架構與 runtime 條件已經顯示 Go 是合適選項，接下來就要理解 Go 為什麼會長成現在這種樣子。簡單、顯式、少魔法是讓高併發服務在多人維護時仍能被快速理解的工程策略。

【觀察】Go 程式的入口通常很直

一個簡化的通知程式，入口可能會做幾件明確的事：

1events := make(chan Event, 128)
2notifications := make(chan Notification, 128)
3
4repo := NewNotificationRepository()
5worker := NewWorker(repo, events, notifications)
6server := NewHTTPServer(repo, notifications)

這段程式沒有依賴注入框架，也沒有隱式容器。所有元件的建立順序、依賴關係、資料流向都直接寫在入口。

這種寫法特別適合服務型應用：當系統需要處理很多並發請求、背景工作或外部事件時，入口越清楚，就越容易確認誰負責什麼、失敗時會停在哪裡。

【判讀】簡單是少猜幾件事

對維護者來說，入口程式的主要工作是回答三個問題：

1. 哪些元件存在？
2. 元件彼此怎麼連接？
3. 程式關閉時誰負責停止？

Go 偏好把這些答案留在表面。當你看到 NewWorker(repo, events, notifications)，你不需要先理解框架規則，就能知道 worker 依賴 repository，從事件 channel 讀資料，輸出通知到另一個 channel。抽象的責任是讓資料流更容易判讀；抽象若讓讀者需要猜測背後規則，就削弱了 Go 在長期維護上的主要價值。

【策略】閱讀 Go 程式先找資料流

讀 Go 應用時，可以用以下順序降低認知負擔：

這個順序先建立系統地圖，再深入單一函式，避免一開始就陷入細節。

【執行】用入口程式畫出資料流

即時通知服務可以先整理成這張資料流：

1file / HTTP / timer ──> events ──> Worker ──> notifications
2                                      │
3                                      ▼
4                                  Repository
5                                      │
6                                      ▼
7                                   HTTP API

這張圖比逐行閱讀更重要。它先回答「系統如何運作」，再讓你回到個別函式確認細節。

本章目標

學完本章後，你將能夠：

1. 用 send lifecycle 判斷誰能 close channel
2. 分辨 sender、receiver、coordinator 的責任
3. 用 channel direction 表達能力限制
4. 設計多 sender 的安全關閉流程
5. 用 context 表達接收端提早停止，而不是關閉不屬於自己的 channel

【觀察】close channel 的核心風險是責任不清

Channel 關閉錯誤的核心問題是 ownership 沒定義清楚。接收端想停止讀取時關閉輸入 channel，多個 sender 中任一個 sender 自行 close，共用 channel 被外部任意 close，這些都可能造成 panic 或資料遺失。

責任不清的示例：

1func Consume(input chan Event) {
2    defer close(input)
3
4    for event := range input {
5        handle(event)
6    }
7}

這段程式的問題是 Consume 只是 receiver，卻關閉了 sender 還可能使用的 channel。只要上游晚一點送資料，就會出現 send on closed channel。

【判讀】close 的語意是不再有新值

close(ch) 的核心語意是「這個 channel 不會再收到新值」。它不是取消 goroutine 的通用手段，也不是釋放記憶體的必要動作。

單一 sender 可以安全 close：

 1func Produce(items []string) <-chan string {
 2    out := make(chan string)
 3
 4    go func() {
 5        defer close(out)
 6        for _, item := range items {
 7            out <- item
 8        }
 9    }()
10
11    return out
12}

這個 goroutine 是唯一 sender，因此它能保證迴圈結束後不再送出。receiver 可以用 range 讀到 channel 關閉為止：

1for item := range Produce([]string{"a", "b"}) {
2    fmt.Println(item)
3}

receiver 不需要 close out。接收完資料是 receiver 的狀態，不代表 sender 的生命週期已經結束。

【策略】先畫出 sender 和 receiver

Channel 設計的核心動作是先列出誰會 send、誰會 receive、誰知道所有 sender 已經結束。這比先決定 buffer 大小更重要。

如果無法回答「誰知道所有 sender 都結束」，就不應該 close 這個 channel。沒有 close 不一定是 bug；錯誤 close 才是更嚴重的問題。

【執行】多 sender 需要 coordinator 關閉

多個 goroutine 送往同一個 channel 時，關閉責任必須交給 coordinator。任一 sender 都不能單方面 close，因為其他 sender 可能還在送。

 1func Merge(inputs ...<-chan Event) <-chan Event {
 2    out := make(chan Event)
 3    var wg sync.WaitGroup
 4
 5    wg.Add(len(inputs))
 6    for _, input := range inputs {
 7        input := input
 8        go func() {
 9            defer wg.Done()
10            for event := range input {
11                out <- event
12            }
13        }()
14    }
15
16    go func() {
17        wg.Wait()
18        close(out)
19    }()
20
21    return out
22}

轉送 goroutine 只負責送資料。另一個 goroutine 等所有 sender 結束後才 close out。這把「送資料」和「宣告所有資料送完」分成兩個責任。

【執行】接收端提早停止要用 context

Receiver 提早停止的核心做法是通知上游停止，而不是關閉輸入 channel。context.Context 是 Go 服務中最常見的停止訊號。

 1func Consume(ctx context.Context, input <-chan Event) error {
 2    for {
 3        select {
 4        case <-ctx.Done():
 5            return ctx.Err()
 6        case event, ok := <-input:
 7            if !ok {
 8                return nil
 9            }
10            handle(event)
11        }
12    }
13}

Consume 可以因為 context 取消而退出，也可以因為 input 關閉而退出。它沒有 close input，因為 input 的 send lifecycle 不屬於它。

這個邊界在服務中很重要。HTTP handler、background worker、connection writer 都可能提早退出，但不能任意 close 上游仍可能使用的 channel。

【策略】channel direction 把能力寫進型別

Channel direction 的核心價值是限制函式能做的事。chan<- T 只能 send，<-chan T 只能 receive；這讓 ownership 更容易被讀者看見。

 1func StartWorker(ctx context.Context, jobs <-chan Job, results chan<- Result) {
 2    for {
 3        select {
 4        case <-ctx.Done():
 5            return
 6        case job, ok := <-jobs:
 7            if !ok {
 8                return
 9            }
10            results <- Process(job)
11        }
12    }
13}

StartWorker 只能從 jobs 收資料，只能往 results 送資料。它不能 close jobs，因為型別上就不是 sender；它是否能 close results 則要看它是不是唯一 sender。

方向限制不會自動解決所有權，但它能減少誤用，也讓 API 比註解更可靠。

【判讀】done channel 和 data channel 分開表達不同語意

停止訊號的核心語意應該和資料流分開。資料 channel 傳遞值；done channel 或 context 表示停止。把兩者混在一起會讓 close 的語意變模糊。

較清楚的設計：

 1type Worker struct {
 2    jobs <-chan Job
 3}
 4
 5func (w Worker) Run(ctx context.Context) {
 6    for {
 7        select {
 8        case <-ctx.Done():
 9            return
10        case job, ok := <-w.jobs:
11            if !ok {
12                return
13            }
14            process(job)
15        }
16    }
17}

jobs 關閉代表沒有更多 job。ctx.Done() 代表上層要求停止。這兩種退出原因不同，分開處理才能在 log、metric 或測試中看清楚。

【測試】測試 close 行為要避免靠 sleep

Channel ownership 的測試目標是確認 sender 結束後會 close、receiver 取消時不會 panic、多 sender 等全部完成才 close。這類測試應使用 channel 同步，不應依賴任意 sleep。

 1func TestProduceClosesOutput(t *testing.T) {
 2    output := Produce([]string{"a"})
 3
 4    if got := <-output; got != "a" {
 5        t.Fatalf("first value = %q, want %q", got, "a")
 6    }
 7
 8    _, ok := <-output
 9    if ok {
10        t.Fatalf("output should be closed after producer finishes")
11    }
12}

多 sender 測試可以讀到輸出 channel 關閉為止，確認所有值都收到：

 1func TestMergeClosesAfterAllInputsClose(t *testing.T) {
 2    a := make(chan Event, 1)
 3    b := make(chan Event, 1)
 4    a <- Event{ID: "a"}
 5    b <- Event{ID: "b"}
 6    close(a)
 7    close(b)
 8
 9    output := Merge(a, b)
10    got := map[string]bool{}
11    for event := range output {
12        got[event.ID] = true
13    }
14
15    if !got["a"] || !got["b"] {
16        t.Fatalf("merge should forward all events before closing")
17    }
18}

這個測試沒有固定等待時間。它把 channel close 本身當成同步訊號，結果更穩定。

本章不處理

本章先聚焦單一 Go process 內的 channel close 與 goroutine lifecycle；跨 process 的 ack、[consumer group](/go-advanced/backend/knowledge-cards/consumer-group) 與分散式訊號，會在下列章節再往外延伸：

• Backend：訊息佇列與事件傳遞
• Backend：可靠性驗證流程

和 Go 教材的關係

這一章承接的是 channel、goroutine 與 select 的協作；如果你要先回看語言教材，可以讀：

• Go：goroutine：輕量並發工作
• Go：channel：資料傳遞與 backpressure
• Go：select：同時等待多種事件
• Go：bounded worker pool

小結

Channel ownership 的核心是 send lifecycle。唯一 sender 可以在送完後 close；多 sender 需要 coordinator 統一 close；receiver 想停止時應使用 context，而不是關閉輸入 channel。把 sender、receiver、coordinator 分清楚，才能避免 send on closed channel、goroutine leak 與資料流混亂。

本章目標

學完本章後，你將能夠：

1. 看懂 go.mod 的三個核心欄位
2. 理解 module path 與 import path 的關係
3. 知道為什麼 Go 指令要在 module 根目錄執行
4. 分辨標準庫與第三方依賴

【觀察】go.mod 定義 module

go.mod 的核心用途是宣告目前 module 的身份、Go 版本與外部依賴。一個 Go 專案通常會在 module 根目錄放 go.mod：

1module example.com/notify-service
2
3go 1.25.1
4
5require (
6    github.com/gorilla/websocket v1.5.3
7)

這份檔案表達三件事：module 名稱、Go 語言版本、外部依賴。

【判讀】module 是 Go 編譯與依賴解析的單位

module 的核心規則是：Go 工具鏈以 go.mod 所在目錄作為依賴解析與 package 掃描的根。Go 工具鏈需要知道「目前這批程式碼」的根在哪裡；go.mod 就是這個根。

當你在 module 根目錄執行：

1go test ./...

./... 的意思是測試目前 module 底下所有 package。實務上要先找到 go.mod 所在目錄，再從那裡執行 Go 指令。

【策略】先分辨三種 import

閱讀 import 的核心規則是：先分辨能力來源，再決定去哪裡查。讀 Go 檔案時，先把 import 分成三類：

這個分類會告訴你：問題應該去查標準庫文件、第三方套件文件，還是目前 module 的其他目錄。

【執行】用 module 模型閱讀 main.go

閱讀入口程式 import 的核心方法是：先把 import 依來源分群，再判斷程式依賴哪些能力。main.go 的 import 可以整理成這樣：

 1import (
 2    "context"
 3    "fmt"
 4    "log/slog"
 5    "net/http"
 6    "os"
 7    "time"
 8
 9    "example.com/notify-service/messages"
10)

前面是標準庫，最後一個是專案內部 package。這表示入口程式主要依賴 Go 標準庫，只有日誌訊息常數被拆到內部 messages package。

本章目標

學完本章後，你將能夠：

1. 分辨 read pump、write pump、hub 的責任
2. 避免多 goroutine 同時寫同一條 WebSocket connection
3. 用 send channel 作為 server-to-client 推送邊界
4. 設計 client unregister 與 close path
5. 用 fake router 測試 read pump 的行為邊界

【觀察】WebSocket 是一條長生命週期雙向連線

WebSocket 連線的核心特徵是 client 和 server 都可能主動送訊息。Client 可能送 subscribe、unsubscribe、ping 或 command；server 可能推送 notification、status update 或 error。

若讀寫責任不分開，程式很容易出現這種結構：

 1func handleConnection(conn *websocket.Conn) {
 2    go func() {
 3        for msg := range serverMessages {
 4            conn.WriteJSON(msg)
 5        }
 6    }()
 7
 8    for {
 9        var msg ClientMessage
10        if err := conn.ReadJSON(&msg); err != nil {
11            return
12        }
13        if msg.Action == "subscribe" {
14            conn.WriteJSON(ServerMessage{Type: "subscribed"})
15        }
16    }
17}

這段程式的問題是多個路徑可能同時寫 connection：背景 goroutine 寫推送，read loop 裡也直接寫回應。多個 goroutine 同時寫 WebSocket 會讓錯誤、資料交錯與 close path 變得難以推理。

【判讀】read pump 和 write pump 是 ownership 邊界

Read pump / write pump 的核心價值是 ownership。Read pump 是唯一讀取者，write pump 是唯一寫入者，其他元件只能透過它們的公開邊界互動。

1type Client struct {
2    id   string
3    conn *websocket.Conn
4    send chan ServerMessage
5}

conn 是底層連線，send 是 server 要推給 client 的訊息佇列。其他元件不直接呼叫 conn.WriteJSON，而是把 ServerMessage 放進 send。

責任表：

這個分工讓連線生命週期可以被測試與替換，而不是散在多個 goroutine 裡。

【策略】Client 型別要表達連線邊界

Client 型別的核心責任是封裝單一連線的狀態與輸出佇列。它不應包含整個系統的業務狀態。

 1type Client struct {
 2    id   string
 3    conn *websocket.Conn
 4    send chan ServerMessage
 5
 6    mu            sync.RWMutex
 7    subscriptions map[string]struct{}
 8}
 9
10func NewClient(id string, conn *websocket.Conn, sendBuffer int) *Client {
11    return &Client{
12        id:            id,
13        conn:          conn,
14        send:          make(chan ServerMessage, sendBuffer),
15        subscriptions: make(map[string]struct{}),
16    }
17}

send 有固定容量，避免慢 client 無限制累積訊息。subscriptions 屬於這條連線的狀態，若會被多個 goroutine 讀寫，就需要 mutex 或集中到 hub event loop。

【執行】read pump 只處理 client 輸入

Read pump 的核心責任是從 connection 讀訊息、轉成 ClientMessage、交給 router。它不應直接操作所有業務規則。

 1type MessageRouter interface {
 2    Route(ctx context.Context, client *Client, message ClientMessage) error
 3}
 4
 5func (c *Client) readPump(ctx context.Context, hub *Hub, router MessageRouter) {
 6    defer func() {
 7        hub.unregister <- c
 8    }()
 9
10    for {
11        var message ClientMessage
12        if err := c.conn.ReadJSON(&message); err != nil {
13            return
14        }
15
16        if err := router.Route(ctx, c, message); err != nil {
17            c.TrySend(ServerMessage{
18                Type:  "error",
19                Error: err.Error(),
20            })
21        }
22    }
23}

Read pump 收到 read error 時退出，並通知 hub unregister。這裡不直接 close send，因為 send 的關閉責任交給 hub 統一處理。

【執行】write pump 是唯一寫入者

Write pump 的核心責任是把 send channel 裡的 server message 寫回 WebSocket。所有寫入都集中在這一個 goroutine，能避免 concurrent write。

 1func (c *Client) writePump() {
 2    for {
 3        message, ok := <-c.send
 4        if !ok {
 5            _ = c.conn.WriteMessage(websocket.CloseMessage, []byte{})
 6            return
 7        }
 8
 9        if err := c.conn.WriteJSON(message); err != nil {
10            return
11        }
12    }
13}

當 send 被關閉時，write pump 送出 close message 並退出。這表示 hub 或 connection manager 是 send 的 owner，write pump 是 receiver。

下一章會把 heartbeat ticker 加進 write pump。原則不變：ping 也是寫入，所以也要由 write pump 統一執行。

【策略】send channel 是推送邊界

send channel 的核心意義是把內部事件轉成 client 輸出佇列。其他元件可以嘗試送訊息，但不能直接寫 connection。

1func (c *Client) TrySend(message ServerMessage) bool {
2    select {
3    case c.send <- message:
4        return true
5    default:
6        return false
7    }
8}

TrySend 使用 non-blocking send，表示 client buffer 滿時不阻塞呼叫端。Hub 可以根據 false 決定丟棄訊息、取消註冊 client 或記錄 metric。

這個方法把 WebSocket 寫入問題轉成前一模組的 backpressure 問題：滿載時要有明確策略。

【執行】hub 統一管理 unregister

Unregister 的核心目標是讓清理流程只有一個責任中心。Read pump、write pump、heartbeat 都可能發現連線失效，但不要讓每個地方各自 close channel 和 connection。

 1type Hub struct {
 2    clients    map[*Client]struct{}
 3    register   chan *Client
 4    unregister chan *Client
 5    broadcast  chan ServerMessage
 6}
 7
 8func (h *Hub) run() {
 9    for {
10        select {
11        case client := <-h.register:
12            h.clients[client] = struct{}{}
13
14        case client := <-h.unregister:
15            if _, ok := h.clients[client]; ok {
16                delete(h.clients, client)
17                close(client.send)
18                _ = client.conn.Close()
19            }
20        }
21    }
22}

這個設計讓 client.send 只會在 hub 中被 close。其他 goroutine 只送 unregister 訊號，不直接關閉資源。

實務上要避免重複 unregister 造成 channel 重複 close。上例透過 clients map 判斷 client 是否仍註冊，讓 unregister 具備 idempotent 行為。

【判讀】read pump 結束不代表 write pump 立刻結束

Read pump 與 write pump 的核心關係是協作，不是互相任意關閉。Read pump 發現錯誤後通知 hub；hub 關閉 send；write pump 收到 send 關閉後送 close message 並退出。

流程：

 1read error
 2   │
 3   ▼
 4hub.unregister <- client
 5   │
 6   ▼
 7hub closes client.send and conn
 8   │
 9   ▼
10write pump exits

這條路徑讓 close ownership 清楚。若 read pump 同時 close send，hub 也 close send，就會有 double close panic。

【測試】router 可以用 fake 驗證 read pump 邊界

Read pump 測試的核心目標是確認 client message 會交給 router，而不是在 read pump 裡塞入業務邏輯。完整 WebSocket integration test 可以留到測試模組；這裡先用 router 的小介面讓行為可替換。

1type fakeRouter struct {
2    messages []ClientMessage
3}
4
5func (r *fakeRouter) Route(ctx context.Context, client *Client, message ClientMessage) error {
6    r.messages = append(r.messages, message)
7    return nil
8}

若測試需要真實 connection，可用 httptest.Server 建立 WebSocket。若只測 router 規則，應直接測 router，不必繞過 network。

Write pump 的測試通常放在 integration test，因為它依賴真實 connection 寫入行為。單元測試則可以集中在 TrySend、router、hub unregister 這些純邊界。

本章不處理

本章先處理單一連線的 read/write ownership；跨節點 hub 與 broker 互動，會在下列章節延伸：

• Go 進階：跨節點 WebSocket、presence 與重連協定

和 Go 教材的關係

這一章承接的是 goroutine ownership、channel 與 backpressure；如果你要先回看語言教材，可以讀：

• Go：goroutine：輕量並發工作
• Go：channel：資料傳遞與 backpressure
• Go：channel ownership 與關閉責任
• Go：如何新增一個即時訊息 action
• Backend：訊息佇列與事件傳遞

小結

Read pump / write pump 模式把一條 WebSocket 連線拆成清楚的 ownership：read pump 讀 client message，write pump 寫 server message，hub 統一註冊與清理。send channel 是推送邊界，所有 close path 應收斂到同一個 unregister 流程。這樣長連線才不會因為 concurrent write、double close 或慢 client 而失控。

本章目標

學完本章後，你將能夠：

1. 定義可序列化成 JSON 的 struct
2. 理解 omitempty 的 API 語義
3. 分辨內部欄位命名與外部 JSON 命名
4. 看懂設定檔、API request 與事件資料模型

【觀察】struct 用欄位集合定義資料形狀

struct 的核心規則是：每個欄位都用名稱和型別描述一部分資料。以下範例用 struct 定義一份應用設定：

1type Config struct {
2    AppName string `json:"appName"`
3    Port    int    `json:"port"`
4    Debug   bool   `json:"debug"`
5}

這段程式同時回答兩個問題：Go 程式內用哪些欄位處理設定，以及 JSON 檔案裡的欄位名稱是什麼。

【判讀】JSON tag 是外部資料格式 contract

JSON tag 的核心規則是：Go 欄位名稱服務程式碼可見性，JSON 欄位名稱服務外部資料格式。AppName 對應 appName 是兩個命名慣例的交界：

omitempty 宣告「這個欄位在某些資料情境中不是必要資料」。它是可選欄位的語義標記；欄位為零值時，JSON 序列化會跳過輸出。

【策略】先用資料語意決定欄位是否必要

設計 JSON 資料時，先分辨欄位角色：

這樣資料 contract 會比「把 struct 全部輸出」更清楚。

【執行】事件資料建模

事件資料模型的核心規則是：事件本身必備欄位不使用 omitempty，事件內容可依類型使用可選欄位。UserEvent 表示一筆使用者行為事件，可以來自檔案、HTTP API 或 message queue：

1type UserEvent struct {
2    UserID    string    `json:"userId"`
3    Type      string    `json:"type"`
4    Timestamp time.Time `json:"timestamp"`
5    Source    string    `json:"source"`
6    Payload   Payload   `json:"payload"`
7}

這個 struct 的欄位都沒有 omitempty，表示它是事件流中的完整資料單位。相比之下，Payload 可以依事件類型使用 omitempty，因為不同事件只會填入部分欄位。

巢狀 struct

巢狀 struct 的核心規則是：資料本身有層次時，Go 型別也應保留同樣層次。以下設定把 server 相關欄位集中到 ServerConfig：

 1type ServerConfig struct {
 2    Host string `json:"host"`
 3    Port int    `json:"port"`
 4}
 5
 6type Config struct {
 7    AppName string       `json:"appName"`
 8    Debug   bool         `json:"debug"`
 9    Server  ServerConfig `json:"server"`
10}

對應 JSON：

1{
2  "appName": "notify",
3  "debug": true,
4  "server": {
5    "host": "localhost",
6    "port": 8080
7  }
8}

這樣的設計讓資料層次在 Go 程式中也看得見。

fmt 負責格式化

fmt 的核心責任是把資料轉成可閱讀的文字。它可以輸出到標準輸出，也可以把格式化結果組成字串，常用於 CLI 訊息、錯誤訊息與簡單除錯。

1name := "worker"
2count := 3
3
4fmt.Printf("%s handled %d jobs\n", name, count)
5message := fmt.Sprintf("%s handled %d jobs", name, count)
6
7fmt.Println(message)

Printf 會直接輸出，Sprintf 會回傳字串。這個差異很重要：函式內部如果只是要建立訊息，通常應該用 Sprintf 回傳字串，而不是直接印出。

格式動詞描述輸出形狀

格式動詞的核心作用是告訴 fmt 如何呈現資料。常見動詞包括 %s 表示字串，%d 表示十進位整數，%v 表示一般值，%+v 顯示 struct 欄位名稱，%#v 顯示更接近 Go 語法的表示。

 1type User struct {
 2    ID   int
 3    Name string
 4}
 5
 6user := User{ID: 7, Name: "alice"}
 7
 8fmt.Printf("%v\n", user)  // {7 alice}
 9fmt.Printf("%+v\n", user) // {ID:7 Name:alice}
10fmt.Printf("%#v\n", user) // main.User{ID:7, Name:"alice"}

%v 適合一般輸出，%+v 適合快速檢查 struct 欄位，%#v 適合除錯或理解實際型別。正式 log 通常應該使用結構化 log，而不是把所有資料塞進格式化字串。

錯誤訊息要包含可行動資訊

錯誤訊息的核心原則是描述失敗的操作與關鍵資料。fmt.Errorf 可以建立帶格式的 error，也可以用 %w 包裝原始錯誤，保留錯誤鏈。

1func loadUser(id string) error {
2    if id == "" {
3        return fmt.Errorf("load user: id is required")
4    }
5
6    return nil
7}

錯誤訊息是給工程師定位問題的線索。像 "failed" 這類訊息太籠統，讀者無法知道是哪個操作失敗。

1if err := saveConfig(path, config); err != nil {
2    return fmt.Errorf("save config %q: %w", path, err)
3}

這裡的訊息包含操作 save config、目標 path 與原始錯誤。呼叫端可以顯示完整錯誤，也可以用 errors.Is 或 errors.As 檢查被包裝的錯誤。

strings 負責字串操作

strings 的核心責任是提供不需要正規表示式的常見字串操作。裁切空白、檢查前後綴、切割、替換、大小寫轉換，都應該先考慮 strings。

1raw := "  api,worker,admin  "
2raw = strings.TrimSpace(raw)
3
4parts := strings.Split(raw, ",")
5for _, part := range parts {
6    fmt.Println(strings.TrimSpace(part))
7}

這段程式先移除整體前後空白，再用逗號切割，最後清理每個片段。這種處理很常見於環境變數、設定檔與簡單文字輸入。

查找與判斷應該直接表達意圖

字串判斷的核心原則是使用最貼近意圖的函式。檢查包含關係用 Contains，檢查開頭用 HasPrefix，檢查結尾用 HasSuffix。

1path := "/api/users"
2
3if strings.HasPrefix(path, "/api/") {
4    fmt.Println("api route")
5}
6
7if strings.Contains(path, "users") {
8    fmt.Println("user resource")
9}

用 Index 判斷是否存在也是可行的，但意圖比較間接。

1if strings.Index(path, "/api/") == 0 {
2    fmt.Println("api route")
3}

這段程式需要讀者理解 Index 回傳 0 表示出現在開頭；HasPrefix 則直接說出規則。入門階段應優先選擇語意清楚的 API。

組合字串要看資料量

組合少量字串時，+ 與 fmt.Sprintf 通常足夠；大量或迴圈內組合字串時，strings.Builder 更適合。核心判斷是：資料量小時重視可讀性，資料量大時避免反覆建立中間字串。

1name := "alice"
2message := "hello, " + name
3fmt.Println(message)

少量字串串接很直覺，不需要過度設計。當你在迴圈中累積文字，strings.Builder 能更明確地表達「正在逐步建構一段文字」。

1var builder strings.Builder
2
3for _, name := range []string{"alice", "bob", "carol"} {
4    builder.WriteString("- ")
5    builder.WriteString(name)
6    builder.WriteString("\n")
7}
8
9fmt.Print(builder.String())

strings.Builder 不是每次組字串都必須使用。若資料量小、流程簡單，普通串接往往更好讀。

簡單 parser 可以先用標準庫

簡單文字解析的核心策略是先用清楚的步驟切割資料，再逐步驗證格式。只有當格式本身複雜到難以維護時，才需要引入 parser 或正規表示式。

 1func parsePair(input string) (string, string, error) {
 2    parts := strings.SplitN(input, "=", 2)
 3    if len(parts) != 2 {
 4        return "", "", fmt.Errorf("parse pair %q: missing =", input)
 5    }
 6
 7    key := strings.TrimSpace(parts[0])
 8    value := strings.TrimSpace(parts[1])
 9    if key == "" {
10        return "", "", fmt.Errorf("parse pair %q: empty key", input)
11    }
12
13    return key, value, nil
14}

SplitN 限制最多切成兩段，避免 value 裡再次出現 = 時被過度切割。這個例子也先處理格式錯誤，再回傳正常結果，讓流程保持清楚。

小結

下一章會進入 time，說明時間點、時間長度與 timeout 的標準表示方式。

本章目標

學完本章後，你將能夠：

1. 理解 heap growth、GOGC 與 GC 頻率的關係
2. 判斷 debug.SetMemoryLimit 能解決什麼、不能解決什麼
3. 從環境變數設定服務 memory limit
4. 用 runtime metrics 觀察調整效果
5. 分辨 GC 壓力、長期保留與真正 leak

【觀察】長時間服務的記憶體問題通常是趨勢問題

記憶體診斷的核心觀察是趨勢。Heap 是否持續上升、GC 後是否下降、goroutine 是否增加、某個操作後是否留下無法回收的資料，這些都比「現在用了多少 MB」更重要。

常見現象：

• 啟動後 heap 穩定在某個區間：通常正常。
• 每次高峰後 heap 都能下降：可能是短暫配置。
• GC 後 heap 仍持續上升：可能有長期保留或 leak。
• GC 次數快速增加且 CPU 升高：可能是 allocation 壓力。
• goroutine 與 heap 同時增加：可能是 goroutine leak 或 send buffer 堆積。

Memory limit 可以幫 runtime 更積極控制 heap，但不能替代趨勢判讀。

【判讀】GC 控制的是 heap 成長

Go GC 的核心目標是回收不再被引用的 heap 物件。Runtime 會根據 GOGC 控制下一次 GC 觸發點。

1GOGC=100 go run ./cmd/server

GOGC=100 大致表示 heap 在上次 GC 後成長約 100% 時觸發下一次 GC。數字越小，GC 越頻繁，記憶體通常較低但 CPU 成本較高；數字越大，GC 較少，記憶體通常較高但 CPU 成本較低。

這是取捨，不是調大或調小就一定更好。CPU 緊繃的服務可能不能承受過低 GOGC；記憶體緊繃的服務可能不能承受過高 GOGC。

【判讀】memory limit 是 runtime 軟目標

debug.SetMemoryLimit 的核心用途是告訴 Go runtime 希望整體記憶體使用量靠近某個目標。當 runtime 接近目標時，會更積極回收 heap。

1func configureRuntime() {
2    const limit = 512 << 20 // 512 MiB
3    debug.SetMemoryLimit(limit)
4}

這不是作業系統層級的硬限制。程式仍可能短暫超過這個值，特別是有大量非 Go heap 記憶體、cgo、mmap、大型 byte slice 尖峰或外部 library 配置時。

Memory limit 適合容器、桌面常駐服務、背景 worker、WebSocket server 這類需要避免吃掉過多資源的服務。若部署平台已有 memory limit，Go runtime 的 limit 通常應略低於平台限制，留給非 Go heap 與系統開銷。

【執行】設定值應來自部署環境

Memory limit 的核心配置原則是由部署環境決定，而不是寫死在 library 裡。應用入口可以讀取環境變數，解析後設定 runtime。

 1func ConfigureMemoryLimitFromEnv() error {
 2    raw := os.Getenv("APP_MEMORY_LIMIT_MB")
 3    if raw == "" {
 4        return nil
 5    }
 6
 7    mb, err := strconv.Atoi(raw)
 8    if err != nil {
 9        return fmt.Errorf("parse APP_MEMORY_LIMIT_MB: %w", err)
10    }
11
12    if mb <= 0 {
13        return fmt.Errorf("APP_MEMORY_LIMIT_MB must be positive")
14    }
15
16    debug.SetMemoryLimit(int64(mb) << 20)
17    return nil
18}

錯誤應在啟動時明確失敗。服務若用錯誤設定悄悄運行，後續記憶體行為會很難解釋。

【策略】runtime metrics 用來看調整是否有效

Runtime metrics 的核心用途是驗證調整效果。只改 GOGC 或 memory limit，不看 heap 與 GC 趨勢，容易變成憑感覺調參。

簡單方式可以用 runtime.ReadMemStats：

1func ReadHeapAlloc() uint64 {
2    var stats runtime.MemStats
3    runtime.ReadMemStats(&stats)
4    return stats.HeapAlloc
5}

較完整的服務可以使用 runtime/metrics：

1func ReadRuntimeSamples() []metrics.Sample {
2    samples := []metrics.Sample{
3        {Name: "/memory/classes/heap/objects:bytes"},
4        {Name: "/gc/cycles/total:gc-cycles"},
5        {Name: "/sched/goroutines:goroutines"},
6    }
7    metrics.Read(samples)
8    return samples
9}

觀察時要看趨勢：調整後 heap 峰值是否下降、GC 次數是否合理、CPU 是否上升、goroutine 是否仍持續增加。

【判讀】memory limit 不能修正仍被引用的資料

Memory limit 的核心邊界是它只能影響 GC 行為，不能讓仍被引用的物件消失。若程式把資料一直留在 map、slice、cache、goroutine 或 send buffer 裡，GC 不能回收。

1var cache = map[string][]byte{}
2
3func SavePayload(id string, payload []byte) {
4    cache[id] = payload
5}

如果 cache 沒有大小限制、TTL 或刪除策略，memory limit 只會讓 GC 更常跑，但資料仍被 cache 引用。真正修正是設計 cache 淘汰、分頁、快照大小限制或資料釋放路徑。

因此遇到 heap 持續上升時，下一步是用 pprof 確認誰保留了記憶體。

【策略】判斷是 GC 壓力還是長期保留

記憶體問題的核心分流是：物件被大量配置但很快回收，還是物件被長期保留。

這個分流會決定後續工具。GC 參數能緩解壓力，但保留資料要回到資料結構與 lifecycle 修。

【測試】runtime 設定函式可以獨立測解析

Runtime 本身不需要在單元測試中反覆調參。應把環境解析邏輯獨立出來，測試輸入與錯誤即可。

 1func ParseMemoryLimitMB(raw string) (int64, error) {
 2    if raw == "" {
 3        return 0, nil
 4    }
 5    mb, err := strconv.Atoi(raw)
 6    if err != nil {
 7        return 0, fmt.Errorf("parse memory limit: %w", err)
 8    }
 9    if mb <= 0 {
10        return 0, fmt.Errorf("memory limit must be positive")
11    }
12    return int64(mb) << 20, nil
13}

測試：

1func TestParseMemoryLimitMB(t *testing.T) {
2    got, err := ParseMemoryLimitMB("512")
3    if err != nil {
4        t.Fatalf("parse memory limit: %v", err)
5    }
6    if got != 512<<20 {
7        t.Fatalf("limit = %d, want %d", got, int64(512<<20))
8    }
9}

這讓設定邏輯可測，而不需要在每個測試中真的改 runtime 狀態。

本章不處理

本章先處理單一 Go process 如何判讀 heap、GC 與 memory limit；平台 OOM 與部署合約，會在下列章節再往外延伸：

• Go 進階：Kubernetes、systemd 與 load balancer 合約
• Backend：部署平台與網路入口

和 Go 教材的關係

這一章承接的是 runtime 壓力、allocation 與 pprof 診斷；如果你要先回看語言教材，可以讀：

• Go：資料結構與 allocation 壓力
• Go：goroutine leak 偵測
• Go：狀態管理的安全邊界
• Go：如何新增背景工作流程

小結

GC 控制 heap 回收節奏，memory limit 給 runtime 一個記憶體軟目標。合理設定能降低長時間服務的資源風險，但不能修正 cache、map、slice、goroutine 或 buffer 長期持有資料。診斷時先看趨勢，再用 pprof 區分 GC 壓力與長期保留。

本章目標

學完本章後，你將能夠：

1. 用 go 啟動 goroutine
2. 理解 goroutine 和一般函式呼叫的差異
3. 判斷哪些工作適合放進 goroutine
4. 為 goroutine 設計退出條件
5. 避免 goroutine leak

【觀察】go 關鍵字啟動並發工作

go 的核心規則是：在函式呼叫前加上 go，該函式會在新的 goroutine 中執行，呼叫端不會等待它完成。

1func say(message string) {
2    fmt.Println(message)
3}
4
5func main() {
6    go say("background")
7    say("foreground")
8}

這段程式啟動一個背景 goroutine 執行 say("background")，主 goroutine 會繼續執行 say("foreground")。

【判讀】goroutine 需要明確完成保證

goroutine 的生命週期規則是：程式不會因為你啟動了 goroutine 就自動等待它完成。main() 結束時，整個 process 會結束，尚未完成的 goroutine 也會停止。

因此，這段程式可能看不到背景輸出：

1func main() {
2    go fmt.Println("background")
3}

主程式太快結束時，背景 goroutine 可能還沒得到執行機會。

需要等待結果時，應該使用 channel、sync.WaitGroup 或其他同步機制。

【策略】goroutine 適合等待型或獨立型工作

goroutine 使用的核心規則是：只有當工作能和目前流程並發進行，且生命週期可被管理時，才啟動 goroutine。

適合 goroutine 的工作：

等待 I/O 的核心訊號是目前流程會花時間等外部回應，例如讀檔、呼叫 HTTP API、等待資料庫查詢或讀取 socket。這類工作放進 goroutine 後，呼叫端可以繼續處理其他事件，但仍然要用 context 或 channel 管理結果與取消。

背景 worker 的核心訊號是工作來自 queue 或 channel，而且處理時間和 request 生命週期分離。例如使用者送出匯入任務後，server 只先接受任務，後續由 worker 逐筆處理資料。這種 goroutine 通常需要明確的 job channel、錯誤回報與 shutdown 流程。

定時任務的核心訊號是行為按時間觸發，例如每分鐘清理過期 session、同步外部狀態或刷新快取。這類 goroutine 應使用 ticker 搭配 context，讓服務停止時可以一起退出。

多個獨立請求的核心訊號是多個工作彼此沒有順序依賴，例如同時查三個外部 API，最後合併結果。這類 goroutine 的重點是收集結果、限制並發數量，並在其中一個工作失敗時決定是否取消其他工作。

需要先補齊生命週期設計的情境：

• 只是想讓程式「看起來比較快」
• 沒有任何退出條件
• 呼叫端需要結果但沒有同步機制
• 多個 goroutine 會同時修改共享資料但沒有保護

【執行】用 WaitGroup 等待一組工作

sync.WaitGroup 的核心用途是等待一組 goroutine 完成。

 1func main() {
 2    var wg sync.WaitGroup
 3
 4    for i := 0; i < 3; i++ {
 5        wg.Add(1)
 6        go func(id int) {
 7            defer wg.Done()
 8            fmt.Println("worker", id)
 9        }(i)
10    }
11
12    wg.Wait()
13}

這段程式有三個關鍵：

id 作為參數傳入 goroutine，可以避免 loop 變數捕捉造成混淆。

長時間 goroutine 要能停止

長時間 goroutine 的核心規則是：迴圈中必須等待取消訊號或輸入 channel 關閉。

 1func worker(ctx context.Context, jobs <-chan Job) {
 2    for {
 3        select {
 4        case <-ctx.Done():
 5            return
 6        case job, ok := <-jobs:
 7            if !ok {
 8                return
 9            }
10            handle(job)
11        }
12    }
13}

這個 worker 不會無限卡住；上層取消 context 或關閉 jobs channel，它都會退出。

設計檢查

需要結果時要有等待機制

需要結果或完成保證時，goroutine 應搭配 channel 或 WaitGroup。go doWork() 只負責啟動工作，結果收集與完成等待需要另外設計。

錯誤要有回報路徑

goroutine 裡的錯誤需要明確回報路徑。需要錯誤結果時，用 channel 傳回：

1errCh := make(chan error, 1)
2go func() {
3    errCh <- doWork()
4}()
5
6if err := <-errCh; err != nil {
7    return err
8}

長時間工作要有退出條件

長時間 worker 至少要監聽 context 或 channel close。永遠 for {} 會讓 goroutine 生命週期失去 owner，服務停止時也難以清理。

本章目標

學完本章後，你將能夠：

1. 分辨 event source、normalizer、processor、repository、publisher 的責任
2. 用 Go interface 表達元件能力，而不是表達資料夾模板
3. 把外部格式限制在 adapter 內
4. 讓狀態更新集中到 repository 或 state owner
5. 用測試驗證每個邊界是否可替換

【觀察】事件流程容易被寫成一團

事件流程膨脹的常見原因是入口程式碼太方便。HTTP handler 可以 decode JSON、驗證欄位、查 map、送通知；worker 也可以讀 queue、判斷重複、更新狀態、寫 log。短期看起來直接，長期會讓每個入口都複製一套規則。

反模式示意：

 1func handleCallback(w http.ResponseWriter, r *http.Request) {
 2    var raw CallbackPayload
 3    json.NewDecoder(r.Body).Decode(&raw)
 4
 5    if raw.ID == "" {
 6        http.Error(w, "missing id", http.StatusBadRequest)
 7        return
 8    }
 9
10    if seen[raw.ID] {
11        w.WriteHeader(http.StatusNoContent)
12        return
13    }
14
15    seen[raw.ID] = true
16    states[raw.AccountID] = "active"
17    hub.Broadcast(raw.AccountID, "active")
18}

這段程式的問題是責任混在一起。HTTP 協定、輸入格式、去重策略、狀態更新與推送規則都被綁在同一個函式，任何一項改變都會影響整個入口。

【判讀】事件邊界應該按照責任切開

事件邊界的核心規則是每一層只知道自己必須知道的資訊。adapter 知道外部協定，normalizer 知道格式轉換，processor 知道事件規則，repository 知道狀態保存，publisher 知道輸出方式。

一個可維護的事件流程可以長這樣：

 1HTTP / queue / timer
 2        │
 3        ▼
 4    adapter
 5        │ raw input
 6        ▼
 7   normalizer
 8        │ DomainEvent
 9        ▼
10   processor
11        │
12        ├── deduper
13        ├── repository
14        └── publisher

這是依賴方向的要求。外部來源依賴內部事件模型；內部處理流程不依賴外部 raw payload。

【策略】先定義內部事件模型

內部事件模型的核心責任是提供穩定語意。不同來源可以有不同欄位名稱與時間格式，但進入 processor 前都應轉成同一種事件。

 1type EventType string
 2
 3const (
 4    EventNotificationCreated EventType = "notification.created"
 5    EventAccountActivated    EventType = "account.activated"
 6    EventJobFinished         EventType = "job.finished"
 7)
 8
 9type EventSource string
10
11const (
12    SourceHTTPCallback EventSource = "http_callback"
13    SourceQueue        EventSource = "queue"
14    SourceTimer        EventSource = "timer"
15)
16
17type DomainEvent struct {
18    ID         string
19    Source     EventSource
20    Type       EventType
21    SubjectID  string
22    OccurredAt time.Time
23    ReceivedAt time.Time
24    Payload    json.RawMessage
25}

OccurredAt 是事件發生時間，ReceivedAt 是系統收到時間。這兩個欄位要分開，因為外部事件可能延遲送達；去重與排序通常看事件語意時間，操作監控通常看收到時間。

【執行】adapter 只負責外部格式

adapter 的核心責任是把外部輸入轉成內部事件或 command。它可以知道 JSON tag、HTTP status、queue ack、header，但不應直接修改狀態。

 1type CallbackPayload struct {
 2    EventID   string `json:"event_id"`
 3    AccountID string `json:"account_id"`
 4    EventName string `json:"event_name"`
 5    Timestamp string `json:"timestamp"`
 6}
 7
 8type CallbackHandler struct {
 9    processor *EventProcessor
10    now       func() time.Time
11}
12
13func (h CallbackHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
14    var payload CallbackPayload
15    if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
16        writeError(w, http.StatusBadRequest, "invalid_json")
17        return
18    }
19
20    event, err := NormalizeCallback(payload, h.now())
21    if err != nil {
22        writeError(w, http.StatusBadRequest, "invalid_event")
23        return
24    }
25
26    if err := h.processor.Process(r.Context(), event); err != nil {
27        writeError(w, http.StatusInternalServerError, "process_event_failed")
28        return
29    }
30
31    w.WriteHeader(http.StatusAccepted)
32}

handler 的測試應該檢查 HTTP 行為與 normalize 錯誤對應。事件規則的測試不應透過 HTTP handler 才能執行，否則 processor 的變化會被協定細節干擾。

【執行】normalizer 負責轉換與基本合約

normalizer 的核心責任是把 raw input 轉成 DomainEvent，並拒絕語意不完整的資料。它是外部世界與內部模型的邊界。

 1func NormalizeCallback(raw CallbackPayload, receivedAt time.Time) (DomainEvent, error) {
 2    occurredAt, err := time.Parse(time.RFC3339, raw.Timestamp)
 3    if err != nil {
 4        return DomainEvent{}, fmt.Errorf("parse timestamp: %w", err)
 5    }
 6
 7    event := DomainEvent{
 8        ID:         strings.TrimSpace(raw.EventID),
 9        Source:     SourceHTTPCallback,
10        Type:       mapCallbackEventName(raw.EventName),
11        SubjectID:  strings.TrimSpace(raw.AccountID),
12        OccurredAt: occurredAt,
13        ReceivedAt: receivedAt,
14    }
15
16    if err := event.Validate(); err != nil {
17        return DomainEvent{}, err
18    }
19    return event, nil
20}
21
22func (e DomainEvent) Validate() error {
23    if e.ID == "" {
24        return fmt.Errorf("event id is required")
25    }
26    if e.Type == "" {
27        return fmt.Errorf("event type is required")
28    }
29    if e.SubjectID == "" {
30        return fmt.Errorf("subject id is required")
31    }
32    if e.OccurredAt.IsZero() {
33        return fmt.Errorf("occurred at is required")
34    }
35    if e.ReceivedAt.IsZero() {
36        return fmt.Errorf("received at is required")
37    }
38    return nil
39}

validation 應該保護 envelope 的必要欄位。更細的 payload 規則可以放在特定事件的 normalizer 或 processor，避免 Validate 變成所有事件的巨大規則表。

【執行】processor 負責事件規則

processor 的核心責任是套用內部事件規則。它可以驗證、去重、更新狀態、寫入事件紀錄、呼叫 publisher，但不應知道 HTTP body 或 queue message 的原始格式。

 1type EventRepository interface {
 2    Apply(ctx context.Context, event DomainEvent) error
 3}
 4
 5type Deduper interface {
 6    Seen(ctx context.Context, event DomainEvent) (bool, error)
 7}
 8
 9type Publisher interface {
10    Publish(ctx context.Context, event DomainEvent) error
11}
12
13type EventProcessor struct {
14    deduper    Deduper
15    repository EventRepository
16    publisher  Publisher
17}
18
19func (p *EventProcessor) Process(ctx context.Context, event DomainEvent) error {
20    if err := event.Validate(); err != nil {
21        return err
22    }
23
24    duplicated, err := p.deduper.Seen(ctx, event)
25    if err != nil {
26        return fmt.Errorf("dedup event: %w", err)
27    }
28    if duplicated {
29        return nil
30    }
31
32    if err := p.repository.Apply(ctx, event); err != nil {
33        return fmt.Errorf("apply event: %w", err)
34    }
35
36    if err := p.publisher.Publish(ctx, event); err != nil {
37        return fmt.Errorf("publish event: %w", err)
38    }
39
40    return nil
41}

這個 processor 依賴能力介面，不依賴具體實作。Go 的 implicit interface 讓 memory repository、database repository 或測試 fake 都可以自然接上。

【判讀】publisher 失敗策略必須明確

publisher 的核心問題是「輸出失敗是否影響狀態成功」。即時通知、審計紀錄、外部 webhook 的可靠性要求不同，不能一律用同一個錯誤策略。

常見策略：

若 repository.Apply 成功但 publisher.Publish 失敗，系統必須知道這是可接受的降級，還是需要重試與補償。這個決策應該寫在 processor 或 usecase 的設計裡，不應藏在 publisher implementation。

【測試】每個邊界分開測

事件邊界的測試目標是讓錯誤定位清楚。normalizer 測 raw input 轉換，processor 測規則順序，repository 測狀態一致性，publisher 測輸出協定。

processor fake test 範例：

 1func TestProcessorSkipsDuplicateEvent(t *testing.T) {
 2    processor := EventProcessor{
 3        deduper:    fakeDeduper{duplicated: true},
 4        repository: &fakeRepository{},
 5        publisher:  &fakePublisher{},
 6    }
 7
 8    err := processor.Process(context.Background(), DomainEvent{
 9        ID:         "evt_1",
10        Type:       EventAccountActivated,
11        SubjectID:  "acct_1",
12        OccurredAt: time.Now(),
13        ReceivedAt: time.Now(),
14    })
15    if err != nil {
16        t.Fatalf("process event: %v", err)
17    }
18
19    if processor.repository.(*fakeRepository).applied {
20        t.Fatalf("duplicate event should not update repository")
21    }
22}

這種測試不需要 HTTP server。它直接驗證 processor 的規則：重複事件不應更新狀態，也不應送出推送。

本章不處理

本章先處理單一 Go 服務內的事件來源與處理邊界；分散式一致性與 event sourcing，會在下列章節再往外延伸：

• Go 進階：資料庫 transaction 與 schema migration
• Go 進階：Durable queue、outbox 與 idempotency
• Backend：資料庫與持久化

和 Go 教材的關係

這一章承接的是 action、event、repository 與 publisher 的邊界；如果你要先回看語言教材，可以讀：

• Go：如何新增一個即時訊息 action
• Go：如何新增一種 domain event
• Go：用 interface 隔離外部依賴
• Go：逐步遷移到 ports/adapters 架構

小結

事件系統的可維護性來自清楚邊界：adapter 處理外部格式，normalizer 建立內部事件，processor 套用規則，repository 擁有狀態，publisher 輸出結果。當每個元件只承擔一種責任時，新增來源、新增事件或替換儲存實作都會變成局部修改。

本章目標

學完本章後，你將能夠：

1. 用 now time.Time 測試純狀態轉移
2. 用 func() time.Time 注入長生命週期元件的時間來源
3. 用 table-driven test 覆蓋時間邊界
4. 把 ticker 排程與單次工作拆開測
5. 避免 time.Sleep 造成慢且不穩定的測試

【觀察】直接呼叫 time.Now 會讓測試失去控制

時間相關邏輯的核心問題是同一筆資料在不同時間會得到不同結果。若函式內部直接呼叫 time.Now()，測試就無法完整控制輸入。

反模式：

1func Status(job Job) string {
2    if job.FinishedAt != nil {
3        return "completed"
4    }
5    if time.Since(job.StartedAt) > 5*time.Minute {
6        return "idle"
7    }
8    return "active"
9}

這個函式看起來簡單，但測試無法指定「現在剛好是開始後 4 分鐘」或「現在剛好跨過 5 分鐘」。測試只能依賴真實時間，結果慢且不穩定。

【判讀】時間是狀態轉移的輸入

時間測試的核心判讀是：如果時間會影響結果，時間就是輸入。把 now 放進函式簽名，會讓狀態轉移規則變得可測。

 1type Job struct {
 2    StartedAt  time.Time
 3    FinishedAt *time.Time
 4}
 5
 6func Status(now time.Time, job Job) string {
 7    if job.FinishedAt != nil {
 8        return "completed"
 9    }
10
11    if now.Sub(job.StartedAt) > 5*time.Minute {
12        return "idle"
13    }
14
15    return "active"
16}

now 是明確輸入，因此測試可以建立任何時間點。這也讓讀者一眼看出 Status 看的是 Job 與目前時間的關係。

【執行】用 table-driven test 描述時間邊界

時間邊界的核心測試方式是列出切換點前後的案例。狀態通常在某個 duration 前後改變，table-driven test 能讓這些情境集中呈現。

 1func TestStatus(t *testing.T) {
 2    startedAt := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
 3
 4    tests := []struct {
 5        name string
 6        now  time.Time
 7        job  Job
 8        want string
 9    }{
10        {
11            name: "active before idle threshold",
12            now:  startedAt.Add(4 * time.Minute),
13            job:  Job{StartedAt: startedAt},
14            want: "active",
15        },
16        {
17            name: "idle after threshold",
18            now:  startedAt.Add(6 * time.Minute),
19            job:  Job{StartedAt: startedAt},
20            want: "idle",
21        },
22        {
23            name: "completed ignores idle threshold",
24            now:  startedAt.Add(30 * time.Minute),
25            job: Job{
26                StartedAt:  startedAt,
27                FinishedAt: ptrTime(startedAt.Add(2 * time.Minute)),
28            },
29            want: "completed",
30        },
31    }
32
33    for _, tt := range tests {
34        t.Run(tt.name, func(t *testing.T) {
35            got := Status(tt.now, tt.job)
36            if got != tt.want {
37                t.Fatalf("Status() = %q, want %q", got, tt.want)
38            }
39        })
40    }
41}