模組一：進階並發模式 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 與資料流混亂。

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 情境下保持可預測。

1.3 非阻塞送出與事件丟棄策略

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

非阻塞送出的核心取捨是用明確降級換取呼叫端可用性。當 channel 滿載時，程式可以等待、回錯、丟棄、覆蓋或轉交可靠儲存；選擇哪一個是服務語意，不是 select 語法偏好。

本章目標

學完本章後，你將能夠：

分辨 blocking send 與 non-blocking send 的服務語意
為 HTTP、worker、即時推送設計不同滿載策略
判斷哪些事件可以丟、哪些不能丟
為 drop 與 queue full 建立 log/metric
測試 channel 滿載時的行為

【觀察】channel 滿載是容量訊號

Channel 滿載的核心意義是下游處理速度跟不上上游輸入速度。這可能是短暫尖峰，也可能是系統長期容量不足。

最直接的 send 會接受 backpressure ：

1events <- event

如果 events 沒有 buffer，或 buffer 已滿，sender 會等待 receiver。這能保留資料，但也可能讓 HTTP handler、connection writer 或其他 goroutine 卡住。

對批次 worker 來說，等待可能合理；對使用者 request 來說，無限等待通常會變成 timeout 或 goroutine 堆積。

【判讀】blocking send 表示願意等待

Blocking send 的核心語意是 sender 接受下游 backpressure 。資料不會被丟掉，但 sender 的生命週期會被 receiver 影響。

有 context 的 blocking send：

1func Enqueue(ctx context.Context, events chan<- Event, event Event) error {
2    select {
3    case events <- event:
4        return nil
5    case <-ctx.Done():
6        return ctx.Err()
7    }
8}

這種寫法仍然願意等待，但不會無限等待。若 request 被取消或 timeout，send 也會停止。

Blocking send 適合資料不能丟、上游能等待、且等待時間受 context 控制的情境。若沒有 context，blocking send 在服務入口通常風險較高。

【判讀】non-blocking send 表示立即選擇替代路徑

Non-blocking send 的核心語意是「能送就送，不能送就立刻走其他策略」。Go 常用 select 加 default 表達。

 1var ErrQueueFull = errors.New("event queue is full")
 2
 3func TryEnqueue(events chan<- Event, event Event) error {
 4    select {
 5    case events <- event:
 6        return nil
 7    default:
 8        return ErrQueueFull
 9    }
10}

這段程式不會等待 receiver。當 buffer 滿載時，呼叫端會立刻拿到 ErrQueueFull，並可以決定回 HTTP 錯誤、記錄 drop、或改走其他儲存。

Non-blocking send 不是比較進階的寫法。它只是把 backpressure 從「等待」改成「立即決策」。

【策略】先定義事件的保留等級

滿載策略的核心判斷是資料語意。每種事件都應先定義保留等級：必須保存、可降級、可覆蓋、可取樣，或可延後處理。這個等級決定 channel 滿載時要等待、回錯、丟棄、覆蓋或轉交可靠儲存。

事件類型	建議策略	理由
audit log	不應直接丟，應寫可靠儲存或回錯	資料遺失會破壞稽核
UI 即時提示	可丟棄或覆蓋	使用者可重新查詢狀態
狀態轉移事件	通常不應丟	會造成 source of truth 不一致
metrics sample	可取樣或丟棄	趨勢比單筆資料重要
background refresh	可跳過本輪	下次仍可重新計算

這個表格的重點是要求每種事件都要有明確策略。若團隊只說「channel 滿了就 default」，通常代表資料語意還沒有想清楚。

【執行】HTTP 入口要把滿載轉成狀態碼

HTTP 入口的核心責任是把內部滿載轉成呼叫端能理解的結果。不要讓 request 一直等到 timeout，也不要把未接受的事件回成成功。

 1func EventHandler(events chan<- Event) http.HandlerFunc {
 2    return func(w http.ResponseWriter, r *http.Request) {
 3        event := Event{ID: r.Header.Get("X-Request-ID")}
 4
 5        if err := TryEnqueue(events, event); err != nil {
 6            if errors.Is(err, ErrQueueFull) {
 7                w.Header().Set("Retry-After", "5")
 8                http.Error(w, "event queue is full", http.StatusServiceUnavailable)
 9                return
10            }
11            http.Error(w, "event enqueue failed", http.StatusInternalServerError)
12            return
13        }
14
15        w.WriteHeader(http.StatusAccepted)
16    }
17}

202 Accepted 表示事件已被服務接受進入後續處理。503 Service Unavailable 表示服務目前無法接受更多事件，呼叫端可以稍後重試。

若事件不能丟，HTTP handler 應該回錯或寫入可靠儲存，不應假裝成功。

【執行】即時推送可以選擇 drop 或 disconnect

即時推送的核心問題是慢 client 不能拖住整個服務。若某個連線的 send buffer 滿了，服務要決定丟掉該訊息、丟掉舊訊息，還是關閉連線。

 1type Client struct {
 2    send chan Message
 3}
 4
 5func (c *Client) TrySend(message Message) bool {
 6    select {
 7    case c.send <- message:
 8        return true
 9    default:
10        return false
11    }
12}

呼叫端可以根據 false 決定策略：

1if ok := client.TrySend(message); !ok {
2    metrics.Inc("client_send_dropped")
3    logger.Warn("drop client message", "reason", "send_buffer_full")
4}

對狀態型 UI 來說，丟掉中間更新可能可以接受，因為下一次 snapshot 會補上最新狀態。對逐筆不可遺失訊息來說，應改用可靠佇列或明確斷線重連協定。

【策略】buffer 只能吸收短暫尖峰

Buffer 的核心作用是平滑短時間流量差，不是解決長期處理能力不足。把 channel buffer 調大，只是延後滿載時間，也可能增加記憶體與延遲。

1events := make(chan Event, 1024)

設計 buffer 時至少要考慮：

單筆事件大小
producer 峰值速度
consumer 穩定處理速度
允許排隊延遲
滿載時的回應策略

若 producer 每秒 1000 筆、consumer 每秒 100 筆，任何有限 buffer 都會滿。這時要改善 consumer 能力、增加 worker、做取樣、回錯或使用可靠 queue，而不是只調大數字。

【策略】丟棄一定要可觀測

Drop strategy 的核心要求是可觀測。只要系統選擇丟棄或降級，就應該留下 metric 或 structured log，否則資料遺失會變成隱性 bug。

 1func TryEnqueueWithMetrics(events chan<- Event, event Event, logger *slog.Logger) error {
 2    select {
 3    case events <- event:
 4        metrics.Inc("event_enqueue_success")
 5        return nil
 6    default:
 7        metrics.Inc("event_enqueue_dropped")
 8        logger.Warn("drop event",
 9            "reason", "queue_full",
10            "event_type", event.Type,
11            "subject_id", event.SubjectID,
12        )
13        return ErrQueueFull
14    }
15}

Log 適合保留單次事件脈絡，metric 適合觀察趨勢。若 drop rate 升高，代表服務正在降級；這應該能被監控看見。

【測試】滿載行為要直接測

Non-blocking send 的測試核心是先讓 channel 滿載，再確認函式立刻回錯。不要用 sleep 等待「可能會滿」。

1func TestTryEnqueueReturnsQueueFull(t *testing.T) {
2    events := make(chan Event, 1)
3    events <- Event{ID: "already_full"}
4
5    err := TryEnqueue(events, Event{ID: "next"})
6    if !errors.Is(err, ErrQueueFull) {
7        t.Fatalf("error = %v, want ErrQueueFull", err)
8    }
9}

Blocking send with context 也可以測：

 1func TestEnqueueStopsWhenContextCanceled(t *testing.T) {
 2    events := make(chan Event)
 3    ctx, cancel := context.WithCancel(context.Background())
 4    cancel()
 5
 6    err := Enqueue(ctx, events, Event{ID: "evt_1"})
 7    if !errors.Is(err, context.Canceled) {
 8        t.Fatalf("error = %v, want context canceled", err)
 9    }
10}

這些測試把滿載和取消變成可重現條件，不需要依賴時間推測。

本章不處理

本章先處理單一 process 內的滿載處理策略；當訊息需要持久化、重試或跨 process 傳遞時，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 channel backpressure 、worker capacity 與事件丟棄策略；如果你要先回看語言教材，可以讀：

小結

非阻塞送出是服務策略，不是語法技巧。Channel 滿載時，系統必須明確選擇等待、回錯、丟棄、覆蓋或轉交可靠儲存。選擇之前先定義事件的保留等級，選擇之後補上 log、metric 與測試，才能讓 backpressure 成為可管理的服務行為。

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、外部突變與難以重現的狀態錯誤。

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；如果你要先回看語言教材，可以讀：

1.6 rate limiting 與 backpressure

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

rate limiting 的核心責任是把過量輸入轉成可預期的服務行為。服務可以等待、排隊、拒絕、降級或取樣，但這些策略應由程式明確決定，而不是讓 goroutine、channel 或 memory 自行失控。

預計補充內容

這些 backpressure 邊界會在下列章節展開：

Go 入門：channel：事件流與 backpressure ：先理解 channel buffer 和等待機制，才知道限流不是只有一種做法。
Go 進階：非阻塞送出與事件丟棄策略：當系統必須在滿載時做出明確選擇，這裡會處理 drop、覆蓋與回錯的語意。
Backend：部署平台與網路入口：跨節點流量治理、gateway 與 quota，屬於平台層責任。

本章不處理

本章先處理單一 process 內的輸入控制與 backpressure ；跨節點流量治理、gateway 與 quota 的平台責任，會放在 Backend：部署平台與網路入口。

與 Backend 教材的分工

本章只處理 Go process 內的速率控制。API gateway、load balancer、service mesh、broker quota 與跨節點流量治理會放在 Backend：部署平台與網路入口。

和 Go 教材的關係

這一章承接的是 channel backpressure 、non-blocking send 與 worker capacity；如果你要先回看語言教材，可以讀：