Goroutine on Tarragon

1.1 channel ownership 與關閉責任

Wed, 22 Apr 2026 00:00:00 +0000

Channel ownership 的核心規則是：能保證不再送出資料的一方，才有資格關閉 channel。建立 channel 的程式碼不一定是 owner；真正的 owner 是掌握 send lifecycle 的元件。

本章目標

學完本章後，你將能夠：

用 send lifecycle 判斷誰能 close channel
分辨 sender、receiver、coordinator 的責任
用 channel direction 表達能力限制
設計多 sender 的安全關閉流程
用 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 大小更重要。

角色	能力	close 責任
single sender	送出資料，知道自己何時結束	擁有 close 責任
receiver	接收資料，可能提早停止	透過 context 通知停止
coordinator	等待所有 sender 結束	擁有 close 責任
external caller	持有 channel reference 但不了解生命週期	不參與 close 決策

如果無法回答「誰知道所有 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) 與分散式訊號，會在下列章節再往外延伸：

和 Go 教材的關係

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

小結

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

2.1 read pump / write pump 模式

Wed, 22 Apr 2026 00:00:00 +0000

Read pump / write pump 的核心規則是單一 WebSocket 連線的讀取與寫入必須分成兩個協調的 goroutine。Read pump 擁有讀取權，write pump 擁有寫入權；其他元件不直接操作底層 connection，而是透過 channel 或 method 協作。

本章目標

學完本章後，你將能夠：

分辨 read pump、write pump、hub 的責任
避免多 goroutine 同時寫同一條 WebSocket connection
用 send channel 作為 server-to-client 推送邊界
設計 client unregister 與 close path
用 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。

責任表：

元件	責任	不應做的事
read pump	讀 client message、交給 router	直接寫 WebSocket
write pump	寫 server message、送 heartbeat、送 close	處理 client action
hub	註冊、取消註冊、廣播	直接讀寫 connection
router	解析 action、呼叫 usecase 或更新訂閱	關閉底層 connection

這個分工讓連線生命週期可以被測試與替換，而不是散在多個 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；如果你要先回看語言教材，可以讀：

小結

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 而失控。

4.1 goroutine：輕量並發工作

Wed, 22 Apr 2026 00:00:00 +0000

goroutine 是 Go 執行並發工作的基本單位。它的核心用途是讓一段函式和目前流程同時進行，但每個 goroutine 都必須有明確的退出條件，否則長時間程式會累積無法回收的背景工作。

本章目標

學完本章後，你將能夠：

用 go 啟動 goroutine
理解 goroutine 和一般函式呼叫的差異
判斷哪些工作適合放進 goroutine
為 goroutine 設計退出條件
避免 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	等檔案、網路、外部程序時不阻塞主流程
背景 worker	從 channel 收 job 並處理
定時任務	定期清理、同步或掃描
多個獨立請求	可同時發出、再收集結果

等待 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}

這段程式有三個關鍵：

動作	意義
`wg.Add(1)`	增加一個待完成工作
`defer wg.Done()`	goroutine 結束時標記完成
`wg.Wait()`	等待所有工作完成

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，服務停止時也難以清理。

模組一：進階並發模式

Wed, 22 Apr 2026 00:00:00 +0000

Go 並發設計的核心是明確定義 ownership、生命週期、 backpressure 與共享狀態邊界。goroutine 很便宜，但失控的 goroutine、關閉錯誤的 channel、無限制堆積的 buffer，以及外洩的可變資料都會讓服務難以維護。

本模組承接入門篇的 goroutine、channel、select、mutex 基礎，進一步處理長時間運行服務會遇到的問題：誰能關閉 channel、worker 如何停止、channel 滿載時怎麼回應、共享 map/slice 如何避免 data race、工作量如何限制、入口速率如何控制。

章節列表

章節	主題	關鍵收穫
1.1	channel ownership 與關閉責任	用 sender lifecycle 判斷誰能 close channel
1.2	select loop 的生命週期設計	同時處理輸入、ticker、取消與資源釋放
1.3	非阻塞送出與事件丟棄策略	把 channel 滿載轉成明確服務行為
1.4	共享狀態與複製邊界	用 lock、copy 與 owner method 保護可變資料
1.5	bounded worker pool	限制同時執行的工作量，避免 goroutine 無限制堆積
1.6	rate limiting 與 backpressure	用本地速率限制保護服務入口與下游依賴

本模組使用的範例主題

本模組使用虛構的通知與工作處理服務作為範例。範例會包含背景 worker、事件佇列、即時推送、狀態 repository 與測試 fake。

範例只用來展示 Go 並發設計方法，不假設讀者正在維護任何特定專案。

本模組的 Go 核心概念

用 channel direction 表達 send-only 與 receive-only 能力。
用 context 作為 goroutine 停止訊號。
用 select 管理多種輸入與 ticker。
用 buffered channel 吸收短暫尖峰，但不把 buffer 當成容量規劃替代品。
用 mutex 保護共享 map/slice。
用 copy boundary 防止呼叫端修改內部狀態。
用 worker pool 控制同時執行數。
用 rate limiter 把過量輸入轉成可預期回應。
用 race detector 與 focused tests 驗證並發邊界。

學習重點

學完本模組後，你應該能判斷：

哪個 goroutine 擁有 channel 的關閉責任
一個長期 worker 停止時需要釋放哪些資源
channel 滿載時應該等待、回錯、丟棄還是降級
map、slice、pointer 何時會洩漏內部狀態
什麼情況下 mutex 比 channel 更適合表達狀態擁有權
什麼情況下需要 bounded worker pool
入口過量時應排隊、限速、拒絕還是降級

本模組不處理

本模組不討論分散式鎖、actor framework 或高階 queue 系統。這些主題建立在本模組的基礎之上；本模組先把單一 Go process 內的 goroutine、worker、速率與共享資料邊界講清楚。外部 broker 與分散式流量治理會放在 Backend：訊息佇列與事件傳遞與 Backend：部署平台與網路入口。

1.2 select loop 的生命週期設計

Wed, 22 Apr 2026 00:00:00 +0000

select loop 的核心責任是管理長時間 goroutine 的生命週期。它不只是等待多個 channel 的語法，而是決定元件如何接收輸入、處理定時任務、回應取消、釋放資源與停止。

本章目標

學完本章後，你將能夠：

拆解 select loop 中每個 case 的責任
用 ctx.Done() 設計一致的退出路徑
正確建立與停止 ticker
處理 channel 關閉後的 nil channel pattern
測試 worker 在事件、ticker、取消下的行為

【觀察】長期 goroutine 通常同時等待多種訊號

長期 goroutine 的核心特徵是它不只處理一種資料。背景 worker 可能同時等待外部事件、定時掃描、清理工作與停止訊號。

 1func (w Worker) Run(ctx context.Context) error {
 2    statusTicker := time.NewTicker(w.statusInterval)
 3    defer statusTicker.Stop()
 4
 5    cleanupTicker := time.NewTicker(w.cleanupInterval)
 6    defer cleanupTicker.Stop()
 7
 8    for {
 9        select {
10        case <-ctx.Done():
11            return ctx.Err()
12        case event, ok := <-w.events:
13            if !ok {
14                return nil
15            }
16            w.processEvent(ctx, event)
17        case <-statusTicker.C:
18            w.scanStatus(ctx)
19        case <-cleanupTicker.C:
20            w.cleanup(ctx)
21        }
22    }
23}

這個 loop 的責任不是「跑一個無限迴圈」，而是定義 worker 活著時能接受哪些訊號，以及停止時要如何退出。

【判讀】select loop 是元件的生命週期表

select loop 的核心價值是把元件生命週期寫成明確表格。每個 case 都應該能回答：收到什麼訊號、代表什麼意思、下一步做什麼。

case	系統意義	下一步
`ctx.Done()`	上層要求停止	回傳 context error
`w.events`	收到外部事件	套用處理流程
`statusTicker.C`	到時間掃描狀態	執行週期任務
`cleanupTicker.C`	到時間清理暫存資料	回收資源

若某個 case 的意義說不清楚，通常代表 worker 責任太多，或事件來源還沒有被整理成清楚的 channel。

【策略】每個長期 goroutine 先回答四個問題

Select loop 設計的核心檢查是生命週期，而不是語法。寫 loop 前先回答四個問題：

誰能停止它？
它消費哪些輸入？
它擁有哪些資源？
停止時要回報錯誤、靜默退出，還是交給上層判斷？

例如：

1type Worker struct {
2    events          <-chan Event
3    statusInterval  time.Duration
4    cleanupInterval time.Duration
5    processor       Processor
6}

Worker 消費 events，擁有兩個 ticker，停止訊號來自 context.Context。這些資訊應該能從型別與 Run 方法看出來，而不是藏在任意 goroutine 裡。

【執行】ticker 要由使用者停止

Ticker 的核心規則是建立者負責停止。time.NewTicker 會建立 runtime 資源；不再使用時應呼叫 Stop。

 1func (w Worker) Run(ctx context.Context) error {
 2    ticker := time.NewTicker(w.interval)
 3    defer ticker.Stop()
 4
 5    for {
 6        select {
 7        case <-ctx.Done():
 8            return ctx.Err()
 9        case <-ticker.C:
10            if err := w.SyncOnce(ctx); err != nil {
11                return err
12            }
13        }
14    }
15}

Ticker 放在 Run 裡建立，表示它的生命週期和 Run 一致。defer ticker.Stop() 讓 worker 不論因為 context、錯誤或 channel 關閉退出，都能釋放 ticker。

如果 ticker 由外部傳入，外部就應該負責停止。擁有權要一致，否則測試和 shutdown 都會變得模糊。

【執行】處理已關閉 channel 要避免忙等

已關閉 channel 的核心行為是讀取會立即回傳零值與 ok=false。在 select loop 裡，如果不處理這件事，loop 可能一直選到同一個已關閉 channel。

當一個輸入關閉後，還要繼續處理其他輸入，可以把它設成 nil：

 1func (w Worker) Run(ctx context.Context) error {
 2    events := w.events
 3    alerts := w.alerts
 4
 5    for events != nil || alerts != nil {
 6        select {
 7        case <-ctx.Done():
 8            return ctx.Err()
 9        case event, ok := <-events:
10            if !ok {
11                events = nil
12                continue
13            }
14            w.processEvent(ctx, event)
15        case alert, ok := <-alerts:
16            if !ok {
17                alerts = nil
18                continue
19            }
20            w.processAlert(ctx, alert)
21        }
22    }
23
24    return nil
25}

Nil channel 在 select 中永遠不會 ready。這讓 worker 能在某個來源關閉後繼續處理其他來源，而不是忙等或提早退出。

【判讀】default case 會改變 loop 的語意

default 的核心效果是讓 select 不等待。這在非阻塞送出很有用，但在長期 worker 的主 loop 中要小心，因為它可能造成 busy loop。

反模式：

 1for {
 2    select {
 3    case <-ctx.Done():
 4        return
 5    case event := <-events:
 6        process(event)
 7    default:
 8        cleanup()
 9    }
10}

當沒有事件時，這個 loop 會不停執行 cleanup()，可能吃滿 CPU。週期任務應該用 ticker 表達，不應用 default 假裝閒置時執行。

較清楚的做法：

 1cleanupTicker := time.NewTicker(time.Minute)
 2defer cleanupTicker.Stop()
 3
 4for {
 5    select {
 6    case <-ctx.Done():
 7        return
 8    case event := <-events:
 9        process(event)
10    case <-cleanupTicker.C:
11        cleanup()
12    }
13}

Ticker 讓頻率明確，也讓測試可以透過可控時間或手動觸發 channel 驗證行為。

【策略】長工作要移出主要 loop

Select loop 的核心風險是某個 case 裡的工作太久，導致其他訊號無法被處理。若 processEvent 可能執行很久，worker 在這段期間就不會回應 context 或 ticker。

可選策略：

策略	適用情境	代價
case 內同步執行	工作短、需要順序處理	慢事件會阻塞整個 loop
啟動 bounded worker pool	工作可並行、需要限制併發	需要排隊與 shutdown 設計
送入另一個 queue	入口要快速接收	需要 backpressure 策略

長工作需要 bounded worker pool、另一個 queue 或明確的同步策略。無限制地在 case 裡 go process(event) 只會把排隊問題從 channel 轉成 goroutine 堆積，並讓 shutdown 和錯誤回報更難處理。

【測試】把單次工作抽成方法

Select loop 的測試核心是避免所有邏輯都只能透過無限迴圈測。把單次工作抽成 SyncOnce、ProcessOne 或 CleanupOnce，可以讓規則測試和 lifecycle 測試分開。

1func (w Worker) SyncOnce(ctx context.Context) error {
2    return w.processor.Sync(ctx)
3}

Run 只負責排程：

1case <-ticker.C:
2    if err := w.SyncOnce(ctx); err != nil {
3        return err
4    }

單次工作測試：

 1func TestSyncOnceCallsProcessor(t *testing.T) {
 2    processor := &fakeProcessor{}
 3    worker := Worker{processor: processor}
 4
 5    if err := worker.SyncOnce(context.Background()); err != nil {
 6        t.Fatalf("sync once: %v", err)
 7    }
 8    if !processor.called {
 9        t.Fatalf("processor should be called")
10    }
11}

Lifecycle 測試則只確認 context 取消能讓 Run 退出：

 1func TestRunStopsOnContextCancel(t *testing.T) {
 2    ctx, cancel := context.WithCancel(context.Background())
 3    cancel()
 4
 5    worker := Worker{
 6        events:          make(chan Event),
 7        statusInterval:  time.Hour,
 8        cleanupInterval: time.Hour,
 9    }
10
11    if err := worker.Run(ctx); !errors.Is(err, context.Canceled) {
12        t.Fatalf("run error = %v, want context canceled", err)
13    }
14}

這種拆法讓測試不需要等待真實 ticker，也不需要在無限 loop 裡猜時間。

本章不處理

本章先把長生命週期 goroutine 的停止、輸入與排空講清楚；更完整的 worker 協調與平台排程責任，會在下列章節再往外延伸：

和 Go 教材的關係

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

小結

select loop 是長期 goroutine 的生命週期表。好的 loop 會明確處理 context 取消、輸入 channel、ticker、資源釋放與 channel 關閉。避免在主 loop 中濫用 default 或無限制開 goroutine，才能讓服務在高流量、錯誤與 shutdown 情境下保持可預測。

3.3 goroutine leak 偵測

Wed, 22 Apr 2026 00:00:00 +0000

Goroutine leak 偵測的核心目標是確認已經沒有存在價值的 goroutine 能被停止。它通常是生命週期問題：誰取消、誰 close、誰解除 I/O 阻塞、誰停止 ticker。

本章目標

學完本章後，你將能夠：

分辨合理長期 goroutine 與 goroutine leak
用 context、done channel、connection close 設計退出路徑
用 pprof goroutine profile 判讀卡住 stack
測試 worker、ticker、WebSocket pump 是否能退出
從 leak pattern 回到 ownership 修正

【觀察】goroutine leak 是生命週期沒有結束

Goroutine leak 的核心定義是某個 goroutine 已經沒有存在價值，卻仍然活著。它可能卡在 channel receive、channel send、network read、ticker、mutex 或永遠不會觸發的 select case。

反模式：

1func StartWorker(jobs <-chan Job) {
2    go func() {
3        for job := range jobs {
4            process(job)
5        }
6    }()
7}

這個 worker 只有在 jobs 被關閉時才會退出。若呼叫端永遠不關閉 jobs，而 worker 也沒有 context，這個 goroutine 可能永久存在。

長期存在不一定是 leak。HTTP server accept loop、metrics exporter、background scheduler 都可能合理存在；問題是它們是否有明確停止條件，且 shutdown 時是否真的會走到。

【判讀】每個 goroutine 都要有退出原因

Goroutine lifecycle 的核心檢查是每個 goroutine 都能回答三個問題：

誰要求它停止？
它如果卡在 channel 或 I/O，如何被喚醒？
它停止後如何讓測試或上層知道？

若三題任一題答不出來，就有 leak 風險。

例如 worker 應該有 context：

 1func RunWorker(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            process(job)
11        }
12    }
13}

這個 worker 有兩條退出路徑：上層取消 context，或 jobs channel 被關閉。這比只依賴 channel close 更容易整合到服務 shutdown。

【策略】I/O 阻塞需要 deadline 或 close

I/O goroutine 的核心風險是 context 本身不一定能打斷底層阻塞呼叫。WebSocket read、TCP read、file watcher、外部 API call 都要確認是否支援 context、deadline 或 close。

WebSocket read pump 常見退出方式：

 1func (c *Client) readPump(ctx context.Context, hub *Hub, router MessageRouter) {
 2    defer func() {
 3        hub.unregister <- c
 4    }()
 5
 6    for {
 7        var message ClientMessage
 8        if err := c.conn.ReadJSON(&message); err != nil {
 9            return
10        }
11        _ = router.Route(ctx, c, message)
12    }
13}

若 ReadJSON 卡住，context 取消不一定直接讓它返回。實務上需要 read deadline、connection close 或 heartbeat 讓 read pump 有機會退出。

【執行】done channel 讓測試能觀察退出

測試 goroutine 是否退出的核心問題是需要可觀察訊號。done channel 可以在 goroutine 結束時 close。

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

測試：

 1func TestRunWorkerStops(t *testing.T) {
 2    ctx, cancel := context.WithCancel(context.Background())
 3    jobs := make(chan Job)
 4    done := make(chan struct{})
 5
 6    go RunWorker(ctx, jobs, done)
 7    cancel()
 8
 9    select {
10    case <-done:
11    case <-time.After(time.Second):
12        t.Fatalf("worker did not stop")
13    }
14}

Timeout 是測試保護，不是功能本身。真正的退出訊號是 done 被關閉。

【執行】ticker 必須停止

Ticker leak 的核心原因是建立 ticker 後沒有呼叫 Stop。Ticker 會持有 runtime 資源；長時間服務若反覆建立不停止，會累積不必要成本。

 1func RunCleanup(ctx context.Context) {
 2    ticker := time.NewTicker(time.Minute)
 3    defer ticker.Stop()
 4
 5    for {
 6        select {
 7        case <-ctx.Done():
 8            return
 9        case <-ticker.C:
10            cleanup()
11        }
12    }
13}

defer ticker.Stop() 應緊跟在成功建立 ticker 後。這樣不管函式因 context、錯誤或 channel 關閉退出，ticker 都會被停止。

time.After 在一次性 timeout 很方便，但在高頻迴圈裡反覆建立 timer 可能造成額外配置。需要重複觸發時，優先使用 Ticker 或可重設的 Timer 並明確停止。

【判讀】pprof goroutine profile 看 stack pattern

Goroutine profile 的核心價值是顯示 goroutine stack。當 goroutine 數量持續上升時，先看它們卡在哪裡。

1curl "http://localhost:8080/debug/pprof/goroutine?debug=2"

常見 pattern：

stack 類型	可能原因	回到哪個邊界
channel receive	上游不會再送，也沒 close/context	channel ownership
channel send	下游不再接收或 buffer 滿	backpressure / unregister
network read	沒有 deadline 或 connection 未 close	heartbeat / I/O lifecycle
ticker loop	context 沒接上或 ticker 未 stop	select loop lifecycle
mutex lock	鎖競爭或死鎖	shared state owner

看到 stack 後，下一步是回到對應 lifecycle 設計：誰負責停止，誰負責釋放阻塞點。

【策略】WebSocket pump leak 要看 read/write/unregister 三方

WebSocket goroutine leak 的核心常見原因是 read pump、write pump、hub unregister 沒有形成閉環。

目標流程：

 1read pump error 或 connection close
 2        │
 3        ▼
 4hub unregister
 5        │
 6        ├── close client.send
 7        └── close conn
 8        │
 9        ▼
10write pump exits

若 hub 沒有 close send，write pump 可能一直等。若 connection 沒有 close，read pump 可能卡在 read。若 unregister 不是 idempotent，重複 close 可能 panic。

Goroutine profile 若顯示大量 goroutine 卡在 writePump 的 send receive，通常要檢查 client.send 是否會被 close。若卡在 ReadJSON，要檢查 read deadline、heartbeat 與 connection close。

【測試】用 goroutine 數量做粗略回歸檢查

Goroutine 數量測試的核心用途是粗略檢查是否有明顯 leak。它不是精準證明，因為 Go runtime 與測試環境本身也會有 goroutine。

 1func TestNoObviousGoroutineLeak(t *testing.T) {
 2    before := runtime.NumGoroutine()
 3
 4    ctx, cancel := context.WithCancel(context.Background())
 5    done := make(chan struct{})
 6    go func() {
 7        defer close(done)
 8        RunWorker(ctx, make(chan Job))
 9    }()
10
11    cancel()
12    select {
13    case <-done:
14    case <-time.After(time.Second):
15        t.Fatalf("worker did not stop")
16    }
17
18    eventually(t, time.Second, func() bool {
19        return runtime.NumGoroutine() <= before+2
20    })
21}

這類測試要留緩衝，避免因 runtime 或其他測試 goroutine 造成假失敗。更可靠的測試仍是等待明確 done 訊號。

【判讀】goroutine leak 修正要改停止路徑

Goroutine leak 的核心修正是補上停止路徑。

常見修正：

加入 ctx.Done() case。
關閉由自己擁有的 output channel。
由 coordinator 等 sender 完成再 close。
對 network read/write 設定 deadline。
shutdown 時 close connection。
ticker 建立後 defer Stop()。
hub unregister 時 close send channel。

修正後要用測試證明退出路徑真的會發生，再用 pprof 或 goroutine count 驗證趨勢。

本章不處理

本章先處理 goroutine 的啟動、停止與阻塞邊界；更完整的 worker 全域治理，會在下列章節再往外延伸：

和 Go 教材的關係

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

小結

Goroutine leak 是生命週期問題。每個長期 goroutine 都應知道誰能停止它、如何解除阻塞、如何讓測試觀察退出。Context、done channel、deadline、connection close、ticker stop 與 hub unregister 是主要工具。pprof goroutine profile 則用來確認還活著的 goroutine 卡在哪個邊界。

1.4 共享狀態與複製邊界

Wed, 22 Apr 2026 00:00:00 +0000

共享狀態的核心規則是同一份可變資料若會被多個 goroutine 存取，就必須有明確 owner 與保護邊界。Map 需要同步，slice 回傳前通常要 copy，可變指標不能隨意暴露，修改行為應集中在擁有狀態的型別內。

本章目標

學完本章後，你將能夠：

判斷哪個型別擁有共享狀態
用 sync.RWMutex 保護 map 與 slice
避免回傳內部 map、slice、pointer
分辨 shallow copy 與 deep copy 的邊界
用測試與 race detector 驗證共享狀態安全性

【觀察】共享狀態風險通常延遲出現

共享狀態的核心風險是錯誤可能只在特定併發時序下出現。單元測試可能通過，本地手動操作也正常，但高流量下會出現 data race、map panic、狀態被外部修改或歷史資料被覆蓋。

反模式示意：

 1type Store struct {
 2    users map[string]User
 3}
 4
 5func (s *Store) Save(user User) {
 6    s.users[user.ID] = user
 7}
 8
 9func (s *Store) Users() map[string]User {
10    return s.users
11}

這個型別有兩個問題：map 沒有同步保護，且 Users 直接暴露內部 map。呼叫端拿到 map 後可以繞過 Store 修改資料。

【判讀】mutex 保護的是狀態不變式

Mutex 的核心責任不是讓程式「不會同時跑」，而是保護某一組資料的不變式。只要讀寫同一份可變資料，就應該由同一個 owner 控制 lock。

 1type UserRepository struct {
 2    mu    sync.RWMutex
 3    users map[string]User
 4}
 5
 6func NewUserRepository() *UserRepository {
 7    return &UserRepository{
 8        users: make(map[string]User),
 9    }
10}

UserRepository 是 users map 的 owner。外部程式不應持有 users 的 reference，也不應知道它用 map、資料庫或其他結構保存。

【執行】所有讀寫都經過 owner method

共享 map 的核心規則是所有讀寫都經過同一組方法。寫入使用 Lock，讀取使用 RLock。

 1func (r *UserRepository) Save(ctx context.Context, user User) error {
 2    r.mu.Lock()
 3    defer r.mu.Unlock()
 4
 5    r.users[user.ID] = user
 6    return nil
 7}
 8
 9func (r *UserRepository) Find(ctx context.Context, id string) (User, bool, error) {
10    r.mu.RLock()
11    defer r.mu.RUnlock()
12
13    user, ok := r.users[id]
14    return user, ok, nil
15}

context.Context 在 memory repository 裡可能用不到，但保留在 method signature 可以讓未來改成資料庫或遠端儲存時支援取消。這是 repository port 常見的演進邊界。

【判讀】回傳內部 map 會破壞 lock

回傳 map 的核心風險是鎖只保護到方法結束。方法回傳後，呼叫端拿到的仍然是同一份 map，任何修改都會繞過 owner。

反模式：

1func (r *UserRepository) UnsafeUsers(ctx context.Context) map[string]User {
2    r.mu.RLock()
3    defer r.mu.RUnlock()
4
5    return r.users
6}

這段程式看起來有加鎖，但鎖釋放後外部仍能修改內部 map：

1users := repo.UnsafeUsers(ctx)
2delete(users, "user_1")

安全做法是回傳 copy：

 1func (r *UserRepository) Users(ctx context.Context) (map[string]User, error) {
 2    r.mu.RLock()
 3    defer r.mu.RUnlock()
 4
 5    result := make(map[string]User, len(r.users))
 6    for id, user := range r.users {
 7        result[id] = user
 8    }
 9    return result, nil
10}

呼叫端可以自由修改 result，不會影響 repository 內部狀態。

【判讀】slice copy 保護的是底層 array

Slice 的核心風險是 slice header 會被複製，但底層 array 可能共享。直接回傳 slice 會讓呼叫端修改 owner 的內部資料。

 1type RecentEvents struct {
 2    mu     sync.RWMutex
 3    events []Event
 4}
 5
 6func (r *RecentEvents) Append(ctx context.Context, event Event) {
 7    r.mu.Lock()
 8    defer r.mu.Unlock()
 9
10    r.events = append(r.events, event)
11}

安全的 list method：

1func (r *RecentEvents) List(ctx context.Context) []Event {
2    r.mu.RLock()
3    defer r.mu.RUnlock()
4
5    result := make([]Event, len(r.events))
6    copy(result, r.events)
7    return result
8}

copy 建立新的底層 array。呼叫端對 result 排序、截斷、append 或修改元素，不會改到 r.events。

【策略】值型別可以 shallow copy，可變欄位需要 deep copy

Copy boundary 的核心判斷是資料裡是否還包含可變 reference。若 struct 只有 string、int、time.Time 這類值型別，shallow copy 通常足夠；若 struct 包含 map、slice 或 pointer，就要考慮 deep copy。

值型別範例：

1type Event struct {
2    ID        string
3    Type      string
4    CreatedAt time.Time
5}

這種 Event 放在 slice 裡，用 copy 複製 slice 通常足夠。

含可變欄位的範例：

1type Event struct {
2    ID       string
3    Type     string
4    Metadata map[string]string
5}

這時只 copy slice 不夠，因為每個 Event.Metadata 仍然指向同一份 map。需要 clone：

 1func CloneEvent(event Event) Event {
 2    cloned := event
 3    if event.Metadata != nil {
 4        cloned.Metadata = make(map[string]string, len(event.Metadata))
 5        for key, value := range event.Metadata {
 6            cloned.Metadata[key] = value
 7        }
 8    }
 9    return cloned
10}

是否需要 deep copy 取決於 API 承諾。如果呼叫端不應修改 repository 內部資料，就要複製所有可變 reference。

【判讀】回傳 pointer 要代表明確修改權

Pointer 回傳的核心語意是呼叫端取得同一份資料的參照。若資料屬於共享狀態，回傳 pointer 通常會破壞 owner 邊界。

容易誤解的 API：

 1func (r *UserRepository) FindPointer(ctx context.Context, id string) (*User, bool) {
 2    r.mu.RLock()
 3    defer r.mu.RUnlock()
 4
 5    user, ok := r.users[id]
 6    if !ok {
 7        return nil, false
 8    }
 9    return &user, true
10}

這段程式回傳的是區域變數 user 的指標，不是 map 內部資料的可修改入口。呼叫端修改這個 pointer，不會保存回 repository。API 看起來像能修改，實際不能，語意不清楚。

更清楚的做法是回傳 value，並提供明確 update method：

 1func (r *UserRepository) UpdateEmail(ctx context.Context, id string, email string) (bool, error) {
 2    r.mu.Lock()
 3    defer r.mu.Unlock()
 4
 5    user, ok := r.users[id]
 6    if !ok {
 7        return false, nil
 8    }
 9
10    user.Email = email
11    r.users[id] = user
12    return true, nil
13}

修改行為集中在 repository 內，lock、驗證與狀態一致性也留在同一個地方。

【策略】mutex 和 channel owner 要按資料形狀選擇

狀態保護的核心選擇是 mutex owner 或 goroutine owner。兩者都符合 Go 的精神，差異在資料存取模式。

方法	適用情境	代價
mutex owner	多個方法需要同步讀寫狀態	要維護 lock 與 copy boundary
goroutine owner	所有修改都能表示成訊息	要設計 command、reply、shutdown

Mutex 版本：

1repo.Save(ctx, user)
2user, ok, err := repo.Find(ctx, id)

Goroutine owner 版本：

1type command struct {
2    kind  string
3    user  User
4    reply chan result
5}

不要為了避免 mutex 而把簡單狀態硬改成複雜訊息系統。也不要在需要嚴格順序與單一事件流時到處加 lock。選擇應該來自資料形狀與讀寫模式。

【測試】copy boundary 要用外部修改驗證

Copy boundary 的測試核心是呼叫 getter 後修改回傳值，再確認 owner 內部資料沒有被改動。

 1func TestUsersReturnsCopy(t *testing.T) {
 2    repo := NewUserRepository()
 3    ctx := context.Background()
 4
 5    if err := repo.Save(ctx, User{ID: "user_1", Email: "a@example.com"}); err != nil {
 6        t.Fatalf("save user: %v", err)
 7    }
 8
 9    users, err := repo.Users(ctx)
10    if err != nil {
11        t.Fatalf("users: %v", err)
12    }
13    delete(users, "user_1")
14
15    _, ok, err := repo.Find(ctx, "user_1")
16    if err != nil {
17        t.Fatalf("find user: %v", err)
18    }
19    if !ok {
20        t.Fatalf("repository should not be modified through returned map")
21    }
22}

Slice copy 也用同樣方式測：

 1func TestEventListReturnsCopy(t *testing.T) {
 2    events := &RecentEvents{}
 3    ctx := context.Background()
 4
 5    events.Append(ctx, Event{ID: "evt_1"})
 6    got := events.List(ctx)
 7    got[0].ID = "changed"
 8
 9    again := events.List(ctx)
10    if again[0].ID != "evt_1" {
11        t.Fatalf("internal event was modified through returned slice")
12    }
13}

這類測試能直接防止未來有人為了「省 copy」而破壞狀態邊界。

【測試】race detector 驗證同步邊界

Race detector 的核心用途是找出未同步的共享記憶體存取。對含有 goroutine、map、slice、repository 的測試，應定期執行：

1go test -race ./...

可以用併發測試增加觸發機率：

 1func TestRepositoryConcurrentAccess(t *testing.T) {
 2    repo := NewUserRepository()
 3    ctx := context.Background()
 4
 5    var wg sync.WaitGroup
 6    for i := 0; i < 100; i++ {
 7        i := i
 8        wg.Add(1)
 9        go func() {
10            defer wg.Done()
11            id := fmt.Sprintf("user_%d", i)
12            _ = repo.Save(ctx, User{ID: id})
13            _, _, _ = repo.Find(ctx, id)
14        }()
15    }
16    wg.Wait()
17}

這個測試本身不一定能證明沒有所有問題，但搭配 -race 可以檢查 repository 方法是否真的包住共享 map。

本章不處理

本章先聚焦單一 Go process 內的共享狀態保護；更外層的資料庫交易、快取一致性與資料複製邊界，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 repository、copy boundary 與 state owner；如果你要先回看語言教材，可以讀：

小結

共享狀態的安全邊界由 owner、lock、copy 與明確修改方法組成。Map/slice 讀寫要經過同一個 owner；getter 不應暴露內部可變資料；含 map、slice、pointer 的 struct 要考慮 deep copy；修改行為應集中在方法內。這些規則能讓長時間運行的 Go 服務避開 data race、外部突變與難以重現的狀態錯誤。

6.4 如何新增背景工作流程

Wed, 22 Apr 2026 00:00:00 +0000

新增背景工作流程的核心規則是先定義生命週期，再定義資料流。worker 是有 context、輸入、輸出、錯誤處理與 shutdown 協定的長期元件。

本章目標

學完本章後，你將能夠：

判斷一段工作是否適合做成 worker
用 Run(ctx) 設計 worker 生命週期
用 channel 和 ticker 表達資料流與週期性工作
處理 queue full、shutdown 與錯誤記錄
分開測試 SyncOnce、Run(ctx) 與 channel 行為

【觀察】worker 是有生命週期的元件

worker 的核心定義是長時間運行、可被啟動、可被取消、會消費輸入或定期執行工作的元件。任意程式碼包進 go func() 只能產生背景 goroutine，還需要生命週期協定才會成為可維護的 worker。

適合做成 worker 的工作通常有三種：

工作類型	範例	worker 責任
queue consumer	從 channel 讀取外部事件	驗證、轉送 processor
periodic task	每 30 秒同步一次外部狀態	產生 command 或 event
cleanup task	定期清理過期資料	呼叫 repository 或 usecase 的清理方法

本章使用「通知同步 worker」作為範例。它定期向外部來源取得通知更新，轉成 domain event，再交給 EventProcessor 處理。

【判讀】worker 責任要先寫清楚

worker 責任的核心問題是它消費什麼、產生什麼、交給誰處理。worker 應聚焦在資料取得、格式轉換與轉交處理器，業務規則、狀態更新與 client 推送要留給對應的 usecase 或 processor。

先定義外部來源：

 1type NotificationSource interface {
 2    FetchUpdates(ctx context.Context) ([]RawNotificationUpdate, error)
 3}
 4
 5type RawNotificationUpdate struct {
 6    ID             string
 7    NotificationID string
 8    Topic          string
 9    Title          string
10    OccurredAt     time.Time
11}

再定義 worker 會呼叫的處理器：

1type EventProcessor interface {
2    Process(ctx context.Context, event DomainEvent) error
3}

worker 的責任是把外部更新取回來、normalize 成 DomainEvent、交給 processor。repository 寫入與推送規則仍然留在 processor 或 usecase 裡。

【策略】把單次工作獨立成 `SyncOnce`

worker 的核心設計技巧是把「單次工作」和「長時間迴圈」分開。SyncOnce 負責做一次同步，Run(ctx) 負責週期性呼叫它。

 1type SyncWorker struct {
 2    source    NotificationSource
 3    processor EventProcessor
 4    logger    *slog.Logger
 5}
 6
 7func NewSyncWorker(source NotificationSource, processor EventProcessor, logger *slog.Logger) *SyncWorker {
 8    return &SyncWorker{
 9        source:    source,
10        processor: processor,
11        logger:    logger,
12    }
13}

SyncOnce 可以像普通函式一樣測試：

 1func (w *SyncWorker) SyncOnce(ctx context.Context) error {
 2    updates, err := w.source.FetchUpdates(ctx)
 3    if err != nil {
 4        return fmt.Errorf("fetch notification updates: %w", err)
 5    }
 6
 7    for _, update := range updates {
 8        event, err := NormalizeNotificationUpdate(update, time.Now())
 9        if err != nil {
10            w.logger.Warn("skip invalid notification update", "id", update.ID, "error", err)
11            continue
12        }
13
14        if err := w.processor.Process(ctx, event); err != nil {
15            return fmt.Errorf("process notification update %s: %w", update.ID, err)
16        }
17    }
18
19    return nil
20}

這裡的 time.Now() 先展示基本寫法；如果測試需要固定時間，可以把 clock 注入進 worker。時間注入會在後面測試章節更完整處理。

【執行】`Run(ctx)` 管理長時間生命週期

Run(ctx) 的核心責任是等待 ticker、呼叫單次工作、尊重取消訊號。它應該在 context 被取消時退出，並釋放 ticker。

 1func (w *SyncWorker) Run(ctx context.Context, interval time.Duration) error {
 2    ticker := time.NewTicker(interval)
 3    defer ticker.Stop()
 4
 5    for {
 6        select {
 7        case <-ctx.Done():
 8            return ctx.Err()
 9        case <-ticker.C:
10            if err := w.SyncOnce(ctx); err != nil {
11                w.logger.Error("sync worker failed", "error", err)
12            }
13        }
14    }
15}

這個版本把單次同步錯誤記錄下來，但不讓 worker 退出。這是策略選擇：若外部來源短暫失敗，worker 可以等待下一輪；若錯誤代表設定失效或授權失效，則可以選擇 return error 讓上層重啟或停止服務。

worker 錯誤策略應該明確。暫時性錯誤通常要記錄後等待下一輪；致命設定錯誤則可以回傳給上層，讓服務決定重啟或停止。

【判讀】channel worker 要設計 backpressure

channel worker 的核心問題是接收端跟不上時要怎麼辦。buffer 大小、blocking send、non-blocking send 都是在回答 backpressure 策略。

假設外部 HTTP callback 會把 raw update 送進 worker queue：

 1type QueueWorker struct {
 2    updates   chan RawNotificationUpdate
 3    processor EventProcessor
 4    logger    *slog.Logger
 5}
 6
 7func NewQueueWorker(processor EventProcessor, logger *slog.Logger, bufferSize int) *QueueWorker {
 8    return &QueueWorker{
 9        updates:   make(chan RawNotificationUpdate, bufferSize),
10        processor: processor,
11        logger:    logger,
12    }
13}

送入 queue 可以選擇 blocking 或 non-blocking。若呼叫端不能被背景處理拖慢，可以用 non-blocking send 並回傳錯誤：

 1var ErrQueueFull = errors.New("notification update queue full")
 2
 3func (w *QueueWorker) Enqueue(update RawNotificationUpdate) error {
 4    select {
 5    case w.updates <- update:
 6        return nil
 7    default:
 8        return ErrQueueFull
 9    }
10}

這個設計很誠實：queue 滿了就是系統忙碌。上層可以記錄 log、回 503，或告訴 client 稍後重試。

【執行】queue worker 要同時監聽輸入與取消

queue worker 的核心生命週期是等待 update 或 context cancel。Run(ctx) 裡應用 select 同時處理這兩件事。

 1func (w *QueueWorker) Run(ctx context.Context) error {
 2    for {
 3        select {
 4        case <-ctx.Done():
 5            return ctx.Err()
 6        case update, ok := <-w.updates:
 7            if !ok {
 8                return nil
 9            }
10            if err := w.handleUpdate(ctx, update); err != nil {
11                w.logger.Error("handle notification update failed", "id", update.ID, "error", err)
12            }
13        }
14    }
15}

handleUpdate 負責單筆資料轉換與處理：

1func (w *QueueWorker) handleUpdate(ctx context.Context, update RawNotificationUpdate) error {
2    event, err := NormalizeNotificationUpdate(update, time.Now())
3    if err != nil {
4        return fmt.Errorf("normalize update: %w", err)
5    }
6    return w.processor.Process(ctx, event)
7}

這裡仍然遵守同一條邊界：worker 不直接改 repository，只把事件交給 processor。

【策略】shutdown 是否 drain queue 要先決定

shutdown 的核心決策是取消時要立刻停止，還是處理完 queue 中既有資料。兩種策略都合理，但語意不同。

策略	做法	適用情境
立即停止	收到 `ctx.Done()` 就 return	即時通知、可重試資料
drain queue	停止接收新資料，處理已排隊資料	不可輕易丟棄的資料

立即停止比較簡單：

1case <-ctx.Done():
2    return ctx.Err()

drain queue 則需要另一個停止接收的協定，例如由擁有送出端的一方關閉 channel，再讓 worker range 到 channel 關閉。channel close 的所有權要留在送出端，因為送出端最清楚是否還會送資料。

這裡的核心區分是「取消 context」和「關閉 channel」代表不同訊號。context 表示這件工作該停了；channel close 表示不會再有新資料。兩者可以搭配，但語意不同。

【判讀】worker 使用服務生命週期 context

worker context 的核心規則是：長時間 worker 使用服務生命週期 context，單次工作可以另外接收 request context。某個 HTTP request 的 context 只適合控制該次請求；request 結束後 context 會被取消。

1func (w *QueueWorker) Enqueue(update RawNotificationUpdate) error {
2    select {
3    case w.updates <- update:
4        return nil
5    default:
6        return ErrQueueFull
7    }
8}

Enqueue 不把 request context 存起來。真正處理 update 時，worker 使用自己的 Run(ctx) context 控制生命週期。

若某筆 update 需要保留 request ID 或 correlation ID，應把它放進明確欄位，而不是依賴 context value 在背景工作中長期存在。

【執行】`SyncOnce` 測試要隔離時間與外部來源

SyncOnce 測試的核心目標是確認單次工作會把外部資料交給 processor。測試重點放在單次同步，不需要等待真實 ticker。

 1type fakeNotificationSource struct {
 2    updates []RawNotificationUpdate
 3    err     error
 4}
 5
 6func (f fakeNotificationSource) FetchUpdates(ctx context.Context) ([]RawNotificationUpdate, error) {
 7    if f.err != nil {
 8        return nil, f.err
 9    }
10    return f.updates, nil
11}
12
13type recordingProcessor struct {
14    events []DomainEvent
15}
16
17func (p *recordingProcessor) Process(ctx context.Context, event DomainEvent) error {
18    p.events = append(p.events, event)
19    return nil
20}

測試單次同步：

 1func TestSyncWorkerSyncOnce(t *testing.T) {
 2    source := fakeNotificationSource{
 3        updates: []RawNotificationUpdate{
 4            {
 5                ID:             "evt_1",
 6                NotificationID: "ntf_1",
 7                Topic:          "deployments",
 8                Title:          "Deploy finished",
 9                OccurredAt:     time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC),
10            },
11        },
12    }
13    processor := &recordingProcessor{}
14    worker := NewSyncWorker(source, processor, slog.Default())
15
16    if err := worker.SyncOnce(context.Background()); err != nil {
17        t.Fatalf("sync once: %v", err)
18    }
19
20    if len(processor.events) != 1 {
21        t.Fatalf("processed events = %d, want 1", len(processor.events))
22    }
23}

這個測試不需要 goroutine。先把單次工作測清楚，再測長時間生命週期。

【執行】`Run(ctx)` 測試要能快速取消

Run(ctx) 測試的核心目標是確認 worker 會尊重取消訊號。測試應該使用已取消或很短的 context，讓測試快速結束。

 1func TestSyncWorkerRunStopsWhenContextCanceled(t *testing.T) {
 2    source := fakeNotificationSource{}
 3    processor := &recordingProcessor{}
 4    worker := NewSyncWorker(source, processor, slog.Default())
 5
 6    ctx, cancel := context.WithCancel(context.Background())
 7    cancel()
 8
 9    err := worker.Run(ctx, time.Hour)
10    if !errors.Is(err, context.Canceled) {
11        t.Fatalf("error = %v, want context.Canceled", err)
12    }
13}

這個測試用 time.Hour 當 interval，因為 context 已經取消，Run 應該立刻退出，不需要等 ticker。

【執行】queue full 測試要固定 buffer

queue full 測試的核心目標是確認 backpressure 策略。buffer 設成 1，先塞滿，再確認第二次 enqueue 回錯。

 1func TestQueueWorkerEnqueueFull(t *testing.T) {
 2    worker := NewQueueWorker(&recordingProcessor{}, slog.Default(), 1)
 3
 4    err := worker.Enqueue(RawNotificationUpdate{ID: "evt_1"})
 5    if err != nil {
 6        t.Fatalf("first enqueue: %v", err)
 7    }
 8
 9    err = worker.Enqueue(RawNotificationUpdate{ID: "evt_2"})
10    if !errors.Is(err, ErrQueueFull) {
11        t.Fatalf("error = %v, want ErrQueueFull", err)
12    }
13}

這個測試不啟動 worker，所以 channel 裡第一筆資料不會被消費，第二筆必然遇到 full。這比用 sleep 製造滿載狀態穩定。

實作檢查清單

新增 background worker 時，可以依序檢查：

worker 責任是否明確：消費什麼，產生什麼，交給誰
是否有 Run(ctx) 作為生命週期入口
單次工作是否拆成 SyncOnce 或 handleUpdate
worker 是否尊重 ctx.Done()
ticker 是否 defer Stop()
channel buffer 是否有明確 backpressure 策略
queue full 是否回錯或記錄，而不是靜默丟棄
worker 是否呼叫 usecase/processor，而不是直接改 repository
測試是否避免真實長時間 sleep

設計檢查

檢查一：goroutine 要有停止條件

長時間 goroutine 需要 context、channel close 或其他退出條件。缺少停止條件時，服務運行越久，越容易累積難以診斷的資源問題。

檢查二：worker 透過 processor 或 usecase 修改狀態

worker 透過 processor 或 usecase 修改狀態，可以讓背景流程和即時流程共用同一套規則。worker 直接改 repository 時，狀態規則容易分散。

檢查三：queue full 要有明確策略

資料可以丟時，應明確記錄 log 或 metric；資料需要保留時，應 blocking 或回錯。queue full 策略明確，後續追蹤才有依據。

檢查四：測試隔離真實時間

測試優先測 SyncOnce，再用已取消 context 測 Run 的退出行為。真實 ticker 等待數秒會讓測試慢且不穩。

本章不處理

本章先處理單一背景工作如何啟動、停止與回報；cron、queue、retry 與 outbox，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 goroutine 生命週期與 event processing；如果你要先回看語言教材，可以讀：

1.5 bounded worker pool

Wed, 22 Apr 2026 00:00:00 +0000

bounded worker pool 的核心責任是限制同時執行的工作量。goroutine 很便宜，但工作本身可能佔用 CPU、memory、file descriptor、外部 API quota 或資料庫連線；worker pool 讓容量限制成為程式設計的一部分。

預計補充內容

這些工作量邊界會在下列章節展開：

Go 入門：goroutine：背景工作與服務生命週期：先理解 goroutine 的啟動和結束方式，才知道 worker pool 為什麼要限制並發數。
Go 入門：channel：事件流與 backpressure ：job channel 的容量和阻塞行為，會直接影響 pool 的整體策略。
Go 進階：select loop 的生命週期設計：worker 的停止、排空與關閉，通常都要回到 select loop 來說明。
Backend：訊息佇列與事件傳遞：真正跨 process 的 consumer、retry 與 dead-letter 行為屬於這裡。

本章不處理

本章先把單一 process 內的工作量上限、停止與排空講清楚；跨 process 的 consumer 與 retry 機制，會放在 Backend：訊息佇列與事件傳遞。

與 Backend 教材的分工

本章只處理單一 Go process 內的工作量限制。跨 process 的 consumer group、broker partition、[dead-letter queue](/go-advanced/backend/knowledge-cards/dead-letter-queue) 與重試政策會放在 Backend：訊息佇列與事件傳遞。

和 Go 教材的關係

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

4.0 Go 並發模型總覽

Wed, 22 Apr 2026 00:00:00 +0000

Go 的並發優勢在於 runtime 讓大量 goroutine 的生命週期、排程與阻塞管理更容易使用。處理高併發時，核心判斷是哪些工作可以並發、哪些資源需要限制，以及 runtime 如何把很多 goroutine 放到有限的 OS thread 上執行。

本章目標

學完本章後，你將能夠：

分辨 process、thread 與 goroutine 的角色
理解 Go 並發與平行執行不是同一件事
看懂為什麼 I/O 型服務特別適合 Go
判斷什麼時候應該限制並發數
了解 Redis 與 SQL 在高併發下為什麼要加邊界

【觀察】goroutine 由 Go runtime 管理

goroutine 是 Go runtime 管理的輕量工作單位，OS thread 則是作業系統實際排程的執行緒。你通常不會直接手動管理 goroutine 對應到哪一條 thread；Go runtime 會負責把很多 goroutine 排程到較少的 OS thread 上。

這表示兩件事：

啟動 goroutine 的成本比建立 thread 低得多。
goroutine 很便宜，不代表下游資源也很便宜。

名稱	責任
process	程式執行的整體容器
OS thread	作業系統真正排程的執行單位
goroutine	Go runtime 管理的並發工作單位
runtime	負責排程、記憶體管理、阻塞處理與 goroutine 生命週期協調

【判讀】並發和平行是不同層次

並發的核心意義是「很多工作在時間上交疊」，平行的核心意義是「真的同時在多個核心上跑」。Go 可以讓你很容易建立並發工作，但是否能同時跑在多核心上，還要看 runtime 排程、CPU 數量與工作型態。

對服務開發來說，這個差異很重要：

I/O-bound 工作通常最適合並發化，因為大部分時間都在等網路、磁碟或外部服務。
CPU-bound 工作不會因為你加很多 goroutine 就自動變快，反而可能因為排程與同步成本變複雜。

【策略】高併發的真正重點是限制下游

Go 的 goroutine 很容易開，但 Redis、SQL、HTTP API、檔案描述元與記憶體 buffer 都有容量上限。高併發設計的核心是替外部資源設邊界，讓 goroutine 數量、下游連線與排隊時間都保持可預期。

常見邊界包括：

worker pool 限制同時處理的工作量
semaphore 或 rate limit 限制入口速率
timeout / deadline 避免單一請求卡太久
queue 或 buffer 對短暫尖峰提供緩衝
backpressure 讓上游看到真實壓力

【應用】Redis 與 SQL 都是 I/O 邊界

Redis 與 SQL 在 Go 裡通常都被當成 I/O 操作來看待：goroutine 負責並發發出請求，但真正的瓶頸通常在網路延遲、連線數、鎖競爭、索引、熱點 key 或 transaction 範圍。

這也是為什麼後面的資料存取章節會反覆強調：

client 或 sql.DB 要共用，不要每個 request 都 new
每個操作都應該帶 context
讀取可以大量並發，但要有連線池和 timeout
寫入可以並發，但要注意衝突、重試與交易邊界
當下游開始飽和時，要有明確的拒絕、排隊或降級策略

【延伸】runtime 細節不必現在全背

本章先建立 runtime 閱讀模型：goroutine 很輕，thread 有成本，下游資源有上限，並發要設邊界。runtime 的完整內部實作可以留到 profiling 與效能診斷階段再深入。

更進一步的診斷與觀察，會在後面的 runtime profiling 與 goroutine leak 章節再補。

本章先處理

這一章先把 Go 的並發模型講清楚；真正落到資料庫與快取時，可以再看：

Backend：資料庫與持久化：看 SQL、transaction、connection pool 與 schema 邊界如何承接服務壓力。
Backend：快取與 Redis：看 Redis client、TTL、eviction、presence store 與 hot key 如何承接服務壓力。
bounded worker pool：把並發數收斂成可控容量。