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

3.1 GC 與 memory limit

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

GC 與 memory limit 的核心關係是：Go runtime 會根據 heap 成長決定何時執行 GC，而 memory limit 讓 runtime 有一個軟性記憶體目標。Memory limit 不是硬性上限，也不是 leak 修復工具；它是讓 runtime 更早回應記憶體壓力的控制訊號。

本章目標

學完本章後，你將能夠：

理解 heap growth、GOGC 與 GC 頻率的關係
判斷 debug.SetMemoryLimit 能解決什麼、不能解決什麼
從環境變數設定服務 memory limit
用 runtime metrics 觀察調整效果
分辨 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 壓力還是長期保留

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

現象	可能問題	下一步
`alloc_space` 高，`inuse_space` 不高	短命配置多，GC 壓力大	找熱路徑 allocation
`inuse_space` 持續上升	長期保留或 leak	看 heap profile retainers
goroutine 數量同步上升	goroutine leak 或 queue 堆積	看 goroutine profile
GC 次數暴增但 heap 仍高	memory limit 壓力或資料保留	檢查 cache/map/buffer

這個分流會決定後續工具。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 教材的關係

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

小結

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

4.1 事件來源、處理流程與狀態邊界

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

事件系統的核心邊界是把「收到訊號」、「轉成事件」、「套用規則」、「更新狀態」與「輸出結果」拆開。每個邊界都應該有自己的型別與測試，否則一個 handler 或 worker 很快就會同時負責協定、驗證、去重、狀態與推送。

本章目標

學完本章後，你將能夠：

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

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

事件流程膨脹的常見原因是入口程式碼太方便。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 的可靠性要求不同，不能一律用同一個錯誤策略。

常見策略：

輸出類型	失敗策略	適用情境
即時 UI 推送	記錄錯誤，可允許狀態已更新	客戶端可重新查詢最新狀態
事件紀錄	失敗時中止流程	紀錄是不可遺失的資料
外部 webhook	寫入 outbox，稍後重試	下游需要可靠接收

若 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 教材的關係

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

小結

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

5.1 時間注入與狀態轉移測試

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

時間控制測試的核心原則是把「現在」變成可指定輸入。只要程式邏輯依賴目前時間、deadline、timeout、ticker 或過期判斷，測試就不應依賴真實等待。

本章目標

學完本章後，你將能夠：

用 now time.Time 測試純狀態轉移
用 func() time.Time 注入長生命週期元件的時間來源
用 table-driven test 覆蓋時間邊界
把 ticker 排程與單次工作拆開測
避免 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}

這個測試不需要 time.Sleep。案例名稱直接描述時間邊界，失敗時能快速定位是哪個規則壞了。

【策略】長生命週期元件用 time provider

Time provider 的核心用途是讓元件在多個方法中取得時間，但測試仍能控制時間來源。最輕量的形式是 func() time.Time。

 1type Monitor struct {
 2    now func() time.Time
 3}
 4
 5func NewMonitor(now func() time.Time) Monitor {
 6    if now == nil {
 7        now = time.Now
 8    }
 9    return Monitor{now: now}
10}
11
12func (m Monitor) Snapshot(job Job) string {
13    return Status(m.now(), job)
14}

測試提供固定時間：

 1func TestMonitorSnapshot(t *testing.T) {
 2    fixedNow := time.Date(2026, 4, 22, 10, 10, 0, 0, time.UTC)
 3    monitor := NewMonitor(func() time.Time {
 4        return fixedNow
 5    })
 6
 7    got := monitor.Snapshot(Job{
 8        StartedAt: fixedNow.Add(-10 * time.Minute),
 9    })
10    if got != "idle" {
11        t.Fatalf("snapshot = %q, want idle", got)
12    }
13}

這比導入大型 clock framework 更輕量，也比在測試裡等待真實時間更可靠。若整個專案有大量時間需求，再考慮統一 clock interface。

【判讀】Ticker 測試要拆排程與工作

Ticker 的核心問題是它同時包含「何時觸發」與「觸發時做什麼」。測試時應把單次工作抽出來，避免為了測狀態規則而等待 ticker。

 1type Worker struct {
 2    syncOnce func(context.Context) error
 3}
 4
 5func (w Worker) Run(ctx context.Context, interval time.Duration) error {
 6    ticker := time.NewTicker(interval)
 7    defer ticker.Stop()
 8
 9    for {
10        select {
11        case <-ctx.Done():
12            return ctx.Err()
13        case <-ticker.C:
14            if err := w.SyncOnce(ctx); err != nil {
15                return err
16            }
17        }
18    }
19}
20
21func (w Worker) SyncOnce(ctx context.Context) error {
22    return w.syncOnce(ctx)
23}

SyncOnce 可以單獨測規則，Run 只需要少數測試確認 context 取消與 ticker 排程。不要讓每個狀態測試都真的啟動 ticker。

【測試】Run 測試應用 context 控制退出

長生命週期 worker 的測試核心是讓退出條件可控。若只想測 context 取消，先取消 context 再呼叫 Run。

 1func TestRunStopsWhenContextCanceled(t *testing.T) {
 2    ctx, cancel := context.WithCancel(context.Background())
 3    cancel()
 4
 5    worker := Worker{
 6        syncOnce: func(context.Context) error {
 7            t.Fatalf("syncOnce should not be called")
 8            return nil
 9        },
10    }
11
12    err := worker.Run(ctx, time.Hour)
13    if !errors.Is(err, context.Canceled) {
14        t.Fatalf("Run() error = %v, want context canceled", err)
15    }
16}

這個測試不需要等待一小時。time.Hour 只是確保 ticker 不會在測試中自然觸發，真正的退出由 context 控制。

【判讀】sleep-based test 應該是例外

Sleep-based test 的核心問題是慢、不穩定、難以定位。排程、CI 負載與機器速度都可能讓測試偶發失敗。

反模式：

1func TestStatusWithSleep(t *testing.T) {
2    start := time.Now()
3    time.Sleep(6 * time.Minute)
4    got := Status(time.Now(), Job{StartedAt: start})
5    _ = got
6}

這種測試不應存在。它拖慢測試套件，仍然不能保證結果穩定。正確做法是直接建構 now 與 StartedAt。

若真的要等待非同步事件，應使用 deadline 與條件重試，而不是固定 sleep；下一章的 integration test 會使用這個原則。

本章不處理

本章先處理時間作為輸入的可測性；更完整的 fake clock 與平台 timeout 合約，會在下列章節再往外延伸：

Go 進階：heartbeat、deadline 與連線清理

和 Go 教材的關係

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

小結

時間控制測試的重點是把時間變成可指定輸入。純邏輯用 now time.Time，長生命週期元件用 func() time.Time，ticker 排程和單次工作分開測。避免 time.Sleep，測試才會快速、穩定且可重現。

6.1 graceful shutdown 與 signal handling

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

Graceful shutdown 的核心目標是服務收到停止訊號後，不再接受新工作，並給既有工作一段時間完成或清理。Go 服務通常用 signal、root context、http.Server.Shutdown、worker context 與 timeout 串起停止流程。

本章目標

學完本章後，你將能夠：

把 OS signal 轉成 root context 取消
用 http.Server.Shutdown 停止接受新 request
讓 worker、hub、WebSocket pump 觀察同一個停止訊號
設計 shutdown timeout 與強制退出邊界
測試 server 與 worker 的停止流程

【觀察】直接結束 process 會留下不確定狀態

Shutdown 的核心風險是停止流程不明確。服務可能正在處理 request、WebSocket client 仍在線、worker 正在寫資料、queue message 尚未 ack、diagnostics 還以為服務可接流量。

不完整停止常見後果：

新 request 在服務即將關閉時仍被接受。
WebSocket client 沒收到 close，server 端 goroutine 殘留。
背景 worker 寫到一半被中斷。
readiness 還是 200，負載平衡器繼續送流量。
測試結束後留下 goroutine 或開放 port。

Graceful shutdown 是讓停止策略可預期。

【判讀】shutdown 是多階段流程

Graceful shutdown 的核心流程是先停止接新工作，再讓既有工作收尾，最後釋放資源。

建議順序：

 1receive SIGINT/SIGTERM
 2        │
 3        ▼
 4cancel root context
 5        │
 6        ├── readiness becomes false
 7        ├── HTTP server stops accepting new requests
 8        ├── workers stop consuming new jobs
 9        ├── WebSocket hub unregisters clients
10        └── diagnostics/log records shutdown reason
11        │
12        ▼
13wait within timeout
14        │
15        ▼
16process exits

不同服務會有不同細節，但核心不變：停止訊號要集中，元件各自完成自己的 cleanup，整體流程要有 timeout。

【執行】signal 轉成 root context

Signal handling 的核心責任是把作業系統訊號轉成應用程式可理解的取消訊號。Go 1.16 之後可以使用 signal.NotifyContext。

1func main() {
2    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
3    defer stop()
4
5    if err := run(ctx); err != nil {
6        log.Fatal(err)
7    }
8}

ctx 是 root context。HTTP server、worker、hub、diagnostics 都應從它派生出自己的 lifecycle，而不是每個元件各自監聽 signal。

Signal handler 不應放大量清理邏輯。它只負責發出停止意圖；實際清理由各元件在自己的 ownership 邊界內完成。

【執行】HTTP server 用 Shutdown 停止接新 request

http.Server.Shutdown 的核心行為是停止接受新連線，並等待既有 request 在 timeout 內完成。它比直接 Close 更適合 graceful shutdown。

 1func RunHTTPServer(ctx context.Context, handler http.Handler) error {
 2    server := &http.Server{
 3        Addr:    ":8080",
 4        Handler: handler,
 5    }
 6
 7    errCh := make(chan error, 1)
 8    go func() {
 9        errCh <- server.ListenAndServe()
10    }()
11
12    select {
13    case <-ctx.Done():
14        shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
15        defer cancel()
16        return server.Shutdown(shutdownCtx)
17
18    case err := <-errCh:
19        if errors.Is(err, http.ErrServerClosed) {
20            return nil
21        }
22        return err
23    }
24}

Shutdown timeout 是必要邊界。沒有 timeout 的 shutdown 可能永遠等待某個卡住 request；timeout 太短則可能讓合理 request 來不及收尾。

【策略】readiness 應先變成 false

Readiness 的核心用途是控制服務是否應接新流量。Shutdown 開始後，readiness 應先變成 false，再停止 server 或等待既有工作。

 1type Lifecycle struct {
 2    shuttingDown atomic.Bool
 3}
 4
 5func (l *Lifecycle) BeginShutdown() {
 6    l.shuttingDown.Store(true)
 7}
 8
 9func (l *Lifecycle) Ready() bool {
10    return !l.shuttingDown.Load()
11}

Signal 收到後：

1lifecycle.BeginShutdown()
2cancel()

這讓負載平衡器或監控能知道服務不應再接新流量。Process 還活著，但 readiness 已經反映操作狀態。

【執行】背景工作要觀察 context

背景 worker 的核心 shutdown 條件是每個 loop 都能觀察停止訊號。Ticker、queue consumer、WebSocket hub 都應該有退出路徑。

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

若 RunOnce 可能執行很久，也應接收 context。否則外層 loop 看到 cancel，內層 I/O 或計算仍可能卡住。

【策略】WebSocket cleanup 要回到 hub owner

WebSocket shutdown 的核心原則是讓 hub 或 connection manager 統一清理 client。不要讓 signal handler 直接遍歷各種 connection 並隨意 close。

 1func (h *Hub) Run(ctx context.Context) {
 2    for {
 3        select {
 4        case <-ctx.Done():
 5            h.closeAllClients()
 6            return
 7        case client := <-h.register:
 8            h.registerClient(client)
 9        case client := <-h.unregister:
10            h.unregisterClient(client)
11        }
12    }
13}

closeAllClients 應透過 hub 的既有 owner 邏輯關閉 send、移除訂閱、關閉 connection。這延續前面模組的 ownership 原則。

【測試】shutdown 測試要觀察明確條件

Shutdown 測試的核心是確認停止訊號能讓元件退出，而不是等待固定時間。

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

HTTP server 測試可以啟動 server 後 cancel context，確認 RunHTTPServer 回傳。測試應使用隨機 port 或 httptest.Server，避免固定 port 造成衝突。

本章不處理

本章先處理服務內部的 shutdown 順序與 cleanup owner；平台 hook、timeout 與 load balancer 合約，會在下列章節再往外延伸：

Go 進階：Kubernetes、systemd 與 load balancer 合約

和 Go 教材的關係

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

小結

Graceful shutdown 是多階段流程：signal 轉成 root context，readiness 先關閉，HTTP server 停止接新 request，worker 和 WebSocket hub 觀察 context 收尾，整體流程受 timeout 保護。停止訊號越集中，元件 ownership 越清楚，服務在部署、測試與本機開發時越不容易留下殘存 goroutine 或未釋放連線。

7.1 資料庫 transaction 與 schema migration

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

資料庫整合的核心責任是讓持久化行為符合 application 的狀態規則。Repository port 決定 usecase 需要哪些資料能力；transaction boundary、schema migration、Expand / Contract 與 isolation level 則決定這些能力在資料庫中如何保持一致。

本章目標

學完本章後，你將能夠：

判斷 [transaction boundary](/go-advanced/backend/knowledge-cards/transaction-boundary) 應該放在 repository 還是 usecase
理解 migration 為什麼要維持向前相容
分辨 application validation、constraint 與 isolation level 的責任
用 contract test 保護 memory repository 與 database repository 的一致行為
讓 SQL 細節留在 adapter，讓 domain 規則留在 application

前置章節

後續撰寫方向

Repository method 如何表達交易語意，讓 SQL 細節留在 adapter。
一個 usecase 需要多筆寫入同時成功或失敗時，transaction boundary 應放在哪裡。
Migration 如何維持向前相容，避免新舊程式版本互相破壞資料。
Isolation level、unique constraint 與 application-level validation 如何分工。
Contract test 如何保護 memory repository 與 database repository 的一致行為。

【觀察】transaction 是一致性邊界

transaction 的核心用途是把一組資料庫操作綁成單一一致性單位。判斷重點是：這個 usecase 哪些狀態要一起成功或一起失敗。效能與寫入便利性都應放在一致性需求之後評估。

例如建立訂單時，可能同時需要：

寫入 order 主表
寫入 order items
更新 inventory
寫入 outbox event

如果其中一個步驟失敗，整組操作就應回滾，避免 application 狀態和資料庫狀態分裂。

【判讀】transaction boundary 應該跟 usecase 對齊

交易邊界最常見的錯誤，是把 transaction 放得太低或太高。

放太低：repository 各自開 transaction，usecase 層看起來成功，實際上無法保證整體一致。
放太高：把不需要一致性的讀取、外部 API、長迴圈也包進 transaction，讓連線被占住太久。

一般原則是：

要維持同一個 domain 不變式的寫入，應放在同一個 transaction。
可以重試或可補償的外部互動，通常應放在 transaction 之外。

【策略】Migration 要讓舊版與新版可以共存

schema migration 的核心是讓部署期間的新舊版本能同時活著。實務上常見的是 Expand / Contract 流程：

先新增欄位、表或索引。
讓新舊程式都能讀寫。
確認流量已切到新版本。
再移除舊欄位或舊邏輯。

這樣做的目的，是避免應用版本與資料庫版本在 rolling deploy 時互相踩到。

【判讀】constraint、validation 與 isolation level 各管不同風險

這三者的責任應清楚分工：

application validation：在進資料庫前先檢查基本輸入是否合法。
unique / foreign key / check constraint：在資料庫層保底，防止不合法資料落地。
isolation level：處理多交易同時進行時的可見性與衝突問題。

如果只靠 application validation，資料庫仍可能被其他路徑寫入不合法資料。如果只靠資料庫 constraint，錯誤回報可能太晚。兩者通常要一起用。

【執行】contract test 檢查 repository 語意一致

當你同時有 memory repository 與 database repository 時，測試重點是它們對外暴露的語意是否一致。SQL 細節屬於 database adapter 的內部實作。

通常要測：

找不到資料時怎麼回傳
重複寫入時怎麼回傳
transaction 失敗時是否維持一致狀態
欄位驗證與預設值是否相同

這類測試可以讓 repository adapter 保持可替換，讓資料庫替換時 usecase 維持穩定。

本章不處理

本章不會選定特定資料庫或 ORM。真正的重點是 Go application 如何定義資料一致性責任，讓 SQLite、PostgreSQL 或其他儲存技術都能成為可替換 adapter。

和 Go 教材的關係

這一章承接的是 Go 的 repository port 與狀態邊界；如果你要先回看語言教材，可以讀：

模組一：進階並發模式

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

2.2 heartbeat、deadline 與連線清理

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

Heartbeat 的核心目標是讓失效的長連線可以被發現並清理。Deadline 定義讀寫最多能停滯多久，ping/pong 在沒有業務訊息時確認連線仍然活著，unregister 流程負責釋放連線與訂閱狀態。

本章目標

學完本章後，你將能夠：

分辨 read deadline、write deadline、ping period、pong wait 的角色
在 read pump 設定 pong handler 與 read limit
在 write pump 用 ticker 統一送 ping
讓 heartbeat 失敗進入同一條 unregister 路徑
測試 timeout 設定與清理流程的邊界

【觀察】長連線可能在沒有錯誤訊息時失效

WebSocket 長連線的核心風險是失效不一定立刻表現成明確錯誤。Client 可能斷網、瀏覽器休眠、代理中斷、行動網路切換，server 的 read 或 write 可能長時間卡住。

沒有 heartbeat 的服務可能出現：

client 已離線，但 server 還保留 client。
訂閱狀態沒有清理，broadcast 仍嘗試推送。
write pump 卡在慢或失效的 connection。
goroutine、send buffer、記憶體逐步累積。

Heartbeat 的目的是讓失敗可以在合理時間內被觀測並進入清理流程。

【判讀】四個時間參數負責不同邊界

Heartbeat 設計的核心是四個時間參數的關係。這些參數是讀寫生命週期的合約。

1const (
2    writeWait  = 10 * time.Second
3    pongWait   = 60 * time.Second
4    pingPeriod = 50 * time.Second
5    maxMessage = 1 << 20
6)

參數	角色	常見關係
`writeWait`	單次寫入最多等待多久	小於 `pongWait`
`pongWait`	多久沒讀到資料就視為失效	大於 `pingPeriod`
`pingPeriod`	多久主動送一次 ping	小於 `pongWait`
`maxMessage`	單筆 client message 大小上限	依協定需求設定

pingPeriod 應小於 pongWait，讓 server 有時間送 ping 並等待 client 回 pong。writeWait 保護每次寫入，避免 write pump 無限卡住。

【執行】read pump 設定 read deadline 與 pong handler

Read deadline 的核心語意是超過指定時間沒有讀取進展，下一次 read 會失敗。Pong handler 的核心責任是每次收到 pong 時延長 read deadline。

1func (c *Client) configureRead() {
2    c.conn.SetReadLimit(maxMessage)
3    _ = c.conn.SetReadDeadline(time.Now().Add(pongWait))
4    c.conn.SetPongHandler(func(string) error {
5        return c.conn.SetReadDeadline(time.Now().Add(pongWait))
6    })
7}

Read pump 啟動時先設定：

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

ReadJSON 回錯時，read pump 不需要判斷每一種錯誤都如何清理；它只要退出並通知 hub。錯誤分類可以用於 log，但清理路徑應一致。

【執行】write pump 用 ticker 送 ping

Ping 的核心規則是由 write pump 送出，因為 ping 也是 WebSocket write。讓其他 goroutine 直接送 ping 會破壞「write pump 是唯一寫入者」的原則。

 1func (c *Client) writePump() {
 2    ticker := time.NewTicker(pingPeriod)
 3    defer ticker.Stop()
 4
 5    for {
 6        select {
 7        case message, ok := <-c.send:
 8            _ = c.conn.SetWriteDeadline(time.Now().Add(writeWait))
 9            if !ok {
10                _ = c.conn.WriteMessage(websocket.CloseMessage, []byte{})
11                return
12            }
13            if err := c.conn.WriteJSON(message); err != nil {
14                return
15            }
16
17        case <-ticker.C:
18            _ = c.conn.SetWriteDeadline(time.Now().Add(writeWait))
19            if err := c.conn.WriteMessage(websocket.PingMessage, nil); err != nil {
20                return
21            }
22        }
23    }
24}

每次寫入前設定 write deadline。這包含正常訊息、ping、close message；只保護部分寫入會留下卡住路徑。

【判讀】heartbeat 失敗走共用清理流程

Heartbeat 失敗的核心語意是連線不可用。它應該進入和 read error、write error、client disconnect 相同的 unregister 流程，而不是在 ping 錯誤處重寫一套清理。

推薦流程：

 1read error / write error / ping error
 2          │
 3          ▼
 4read pump exits or write pump exits
 5          │
 6          ▼
 7hub unregisters client
 8          │
 9          ▼
10close send, close conn, remove subscriptions

實作可以用 hub unregister channel、context cancellation 或 connection manager。重點是所有失效都收斂到同一個 owner。

【策略】read pump 和 write pump 都可能先失敗

連線失效的核心不確定性是 read pump 和 write pump 哪個先看到錯誤不可預測。讀不到 pong 可能讓 read pump 先退出；寫 ping 失敗可能讓 write pump 先退出。

因此 unregister 必須可重複呼叫而不出錯：

1func (h *Hub) unregisterClient(client *Client) {
2    if _, ok := h.clients[client]; !ok {
3        return
4    }
5
6    delete(h.clients, client)
7    close(client.send)
8    _ = client.conn.Close()
9}

用 clients map 判斷 client 是否仍註冊，可以避免重複 close send。這是 WebSocket cleanup 最容易漏掉的細節之一。

【策略】heartbeat 參數要符合部署環境

Heartbeat 參數的核心取捨是偵測速度與誤判風險。偵測太快會讓短暫網路抖動造成大量斷線；偵測太慢會讓失效連線保留太久。

調整時要考慮：

load balancer 或 proxy idle timeout
行動網路與瀏覽器背景分頁行為
server 可接受的失效連線保留時間
ping 對大量連線造成的週期性流量
client 是否會自動重連

若基礎設施會在 60 秒 idle 後關閉連線，server 的 ping period 就不能長於這個時間。這是部署環境合約，不是單純 Go 程式碼問題。

【測試】把時間參數和清理邊界拆開測

Heartbeat 的測試核心是不要用真實分鐘級等待。時間參數可以測設定值關係，清理流程可以測 unregister 是否 idempotent。

1func TestHeartbeatDurations(t *testing.T) {
2    if pingPeriod >= pongWait {
3        t.Fatalf("pingPeriod must be smaller than pongWait")
4    }
5    if writeWait >= pongWait {
6        t.Fatalf("writeWait should be smaller than pongWait")
7    }
8}

Unregister 測試：

 1func TestUnregisterClientIsIdempotent(t *testing.T) {
 2    hub := NewHub()
 3    client := NewClient("c1", nil, 1)
 4    hub.clients[client] = struct{}{}
 5
 6    hub.unregisterClient(client)
 7    hub.unregisterClient(client)
 8
 9    if _, ok := hub.clients[client]; ok {
10        t.Fatalf("client should be removed")
11    }
12}

真實 ping/pong 行為適合放在 integration test。單元測試先保證時間合約與 cleanup owner 不會被破壞。

本章不處理

本章先處理單一 WebSocket 連線的存活偵測與 cleanup；client 重連與 load balancer 參數，會在下列章節延伸：

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

和 Go 教材的關係

這一章承接的是 read/write pump、time control 與 shutdown；如果你要先回看語言教材，可以讀：

小結

Heartbeat/deadline 的目的是讓失效連線在可預期時間內被發現並清理。Read deadline 搭配 pong handler 保護讀取端，write deadline 保護每次寫入，ping ticker 由 write pump 統一執行，所有錯誤最後都應進入同一個 unregister 流程。

3.2 pprof 基礎診斷流程

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

pprof 的核心用途是用實際執行資料定位效能問題。它能協助觀察 heap、goroutine、CPU、block、mutex 與 trace，讓工程師從「感覺哪裡慢」改成「依 profile 判斷哪裡有壓力」。

本章目標

學完本章後，你將能夠：

安全地條件啟用 pprof endpoint
判斷 heap、goroutine、CPU、block、mutex、trace 各自回答什麼問題
用 go tool pprof 取得 profile 並閱讀 top
區分 inuse_space 與 alloc_space
把 profile 結果連回程式設計邊界

【觀察】效能問題需要先問對問題

pprof 診斷的核心起點是先確認你要回答哪個問題。不同 profile 回答不同問題，拿錯工具會讓分析變成猜測。

問題	優先 profile
記憶體持續上升	heap `inuse_space`
GC 壓力高、配置很多	heap `alloc_space`
goroutine 數量持續增加	goroutine profile
CPU 使用率高	CPU profile
goroutine 常卡在 channel 或 syscall	goroutine / trace
mutex 等待嚴重	mutex profile
channel/send/receive 阻塞多	block profile

Profile 不是一次全抓就會自動給答案。先問清楚問題，再抓對應資料，分析成本會低很多。

【判讀】pprof endpoint 是受控診斷入口

pprof endpoint 的核心安全責任是受控地暴露診斷資訊。它可能包含 goroutine stack、函式名稱、路徑、記憶體配置模式與部分請求脈絡；正式服務應把 /debug/pprof/ 放在明確啟用、內部網路或驗證保護之後。

條件啟用範例：

1import _ "net/http/pprof"
2
3func RegisterDebugEndpoints(mux *http.ServeMux) {
4    if os.Getenv("APP_PPROF") != "1" {
5        return
6    }
7
8    mux.Handle("/debug/pprof/", http.DefaultServeMux)
9}

實務上還可以只綁定 localhost、掛在內部管理 port、加上身份驗證，或只在開發與診斷環境啟用。重點是 pprof 要受控，而不是跟公開 API 一起裸露。

【執行】heap profile 看記憶體保留與配置壓力

Heap profile 的核心問題是「哪些物件佔用或配置了記憶體」。當服務記憶體持續上升時，heap profile 是第一個常用工具。

看目前仍被保留的記憶體：

1go tool pprof http://localhost:8080/debug/pprof/heap

進入 pprof 後：

1(pprof) top

inuse_space 代表目前仍被保留的記憶體，適合分析 leak、cache、map、slice、send buffer、長期持有資料。

看累積配置量：

1go tool pprof -alloc_space http://localhost:8080/debug/pprof/heap

alloc_space 代表累積配置量，適合分析 JSON marshal、slice append、短命 object、熱路徑反覆配置造成的 GC 壓力。

【判讀】heap profile 要連回資料結構

Heap profile 的核心解讀是問「誰持有資料」或「誰反覆配置」。看到某個函式在 top 裡，下一步要回到資料結構與生命週期。

常見對應：

profile 現象	可能設計問題
map 持續佔用	cache 沒有淘汰或 key 無限制成長
slice/history 佔用高	history 無上限或 list 回傳太大
JSON marshal alloc 高	高頻推送每個 client 重複 marshal
bytes.Buffer 配置高	熱路徑重複建立 buffer
websocket message 佔用高	send buffer 滿載或慢 client

Profile 給的是線索，不是最終修正。修正要回到資料模型、copy boundary、buffer policy 或 cache policy。

【執行】goroutine profile 看存活與卡住路徑

Goroutine profile 的核心問題是「哪些 goroutine 還活著，以及它們卡在哪裡」。它常用來診斷 goroutine leak、channel 等待、鎖等待與 network read 阻塞。

互動模式：

1go tool pprof http://localhost:8080/debug/pprof/goroutine

文字 stack：

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

若大量 goroutine 卡在同一個 channel receive、send、network read、ticker loop，通常代表某個退出條件、close path、deadline 或 unregister 設計有問題。

Goroutine profile 不只看數量。少量但卡在錯誤位置的 goroutine，也可能代表資源沒有被釋放。

【執行】CPU profile 看熱路徑

CPU profile 的核心問題是「程式把 CPU 時間花在哪裡」。它需要採樣一段時間，適合分析 CPU 使用率高或 request latency 異常。

1go tool pprof "http://localhost:8080/debug/pprof/profile?seconds=30"

常用指令：

1(pprof) top
2(pprof) list Encode

CPU profile 要搭配流量情境解讀。低流量時抓到的 profile 可能沒有代表性；高流量時則要注意診斷本身也會造成額外負擔。

若 top 顯示大量時間花在 JSON encode、sort、lock、regex 或 compression，下一步應回到對應熱路徑，判斷是否可以減少工作、快取結果、改資料結構或降低呼叫頻率。

【策略】block 與 mutex profile 需要先啟用取樣

Block/mutex profile 的核心用途是分析等待，而不是分析 CPU 計算。它們通常需要在程式中設定取樣比例。

1func ConfigureBlockingProfiles() {
2    runtime.SetBlockProfileRate(1)
3    runtime.SetMutexProfileFraction(5)
4}

Block profile 看 goroutine 在同步原語上阻塞的時間，例如 channel send/receive、select、mutex。Mutex profile 看鎖競爭。

啟用取樣有成本，不一定要常駐開最高強度。診斷時可以條件啟用，或在壓測環境中使用。

【執行】trace 看排程與延遲

Trace 的核心用途是觀察 goroutine 排程、network block、syscall、GC pause 與延遲事件。它比單一 profile 更完整，但也更重。

1curl -o trace.out "http://localhost:8080/debug/pprof/trace?seconds=5"
2go tool trace trace.out

Trace 適合用在你已經知道有延遲問題，但 heap、CPU、goroutine profile 都不足以解釋時。它能顯示 goroutine 何時 runnable、何時 blocked、何時被排程。

Trace 檔案可能很大，不適合長時間收集。通常先抓短時間，確認問題窗口後再精準分析。

【策略】診斷流程要先保留現場

pprof 診斷的核心流程是先保留現場，再改程式。若你先重啟服務或調參，可能會清掉最重要的證據。

建議流程：

記錄當下流量、版本、操作、時間區間。
讀 runtime metrics：heap、GC、goroutine、queue 長度。
依問題抓 profile：heap、goroutine、CPU 或 trace。
用 profile 找出函式與 stack pattern。
回到程式碼確認資料結構、goroutine lifecycle 或 hot path。
修改後用相同情境再抓一次 profile 驗證。

這個流程能避免「看到 top 第一名就改」的衝動。Profile 需要和情境一起讀，才不會誤判。

本章不處理

本章先處理單一服務內的 profile 讀法；商用 APM 與分散式 tracing，會在下列章節再往外延伸：

和 Go 教材的關係

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

小結

pprof 是診斷工具，不是公開 API。Heap profile 看保留與配置，goroutine profile 看存活與卡住路徑，CPU profile 看熱點，block/mutex profile 看等待，trace 看排程與延遲。好的診斷流程會先問對問題、抓對 profile，再把結果連回資料結構、goroutine lifecycle 與服務行為。

4.2 事件去重與語義鍵設計

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

事件去重的核心規則是用領域語意判斷「哪兩筆事件代表同一件事」。原始 payload、request ID、收到時間和重試次數常常每次都不同，直接拿來比對會讓去重失效。

本章目標

學完本章後，你將能夠：

分辨 event ID 去重與 domain key 去重的差異
用 subject、event type、source group 與時間窗口設計 DedupKey
避免把不穩定欄位放進去重鍵
設計去重表的過期與清理策略
用 table-driven test 驗證去重邊界

【觀察】重複事件不一定長得一樣

重複事件的核心困難是外觀可能不同。HTTP callback 可能每次都有新的 request ID，queue message 可能因 retry 改變 delivery tag，timer 可能在下一輪掃描再次產生類似事件。

兩筆外部輸入可能長這樣：

1{
2  "request_id": "req_1001",
3  "event_id": "provider_7788",
4  "account_id": "acct_1",
5  "event_name": "activated",
6  "timestamp": "2026-04-22T10:00:03Z"
7}

1{
2  "request_id": "req_1002",
3  "event_id": "provider_7788_retry",
4  "account_id": "acct_1",
5  "event_name": "activated",
6  "timestamp": "2026-04-22T10:00:05Z"
7}

如果直接比對整包 JSON，這兩筆不同；如果從 domain 看，它們可能都是「同一個 account 在同一小段時間內變成 active」。

【判讀】去重鍵是語意決策

去重鍵的核心責任是把「相同事件」的定義寫進型別。它不是單純把 payload 做 hash；hash 只能回答 bytes 是否相同，不能回答領域事件是否相同。

1type DedupKey struct {
2    SubjectID string
3    Type      EventType
4    SourceSet string
5    Window    int64
6}

這個 key 表示：同一個 subject、同一種 event type、同一組來源語意、落在同一個時間窗口的事件，視為同一件事。

SourceSet 不一定等於原始來源名稱。多個來源若只是同一件事的不同傳輸管道，可以映射到同一個 source set；若兩個來源代表不同權威資料，則應分開。

【策略】先選擇去重層級

去重層級的核心選擇是 event ID、domain key 或兩者並用。不同層級解決的問題不同。

去重方式	判斷依據	適用情境	風險
event ID	外部或內部 event ID 相同	上游提供穩定唯一 ID	上游 retry 可能換 ID
domain key	subject、type、時間窗口相同	多來源可能描述同一件事	key 設太粗會誤殺事件
兩者並用	event ID 先判斷，再用 domain key 補強	上游 ID 大多可信但不完全穩定	實作與測試較複雜

小型服務可以先使用 domain key。若上游提供可靠 event ID，則 event ID 可以成為第一層快速去重，domain key 作為跨來源重複的保護。

【執行】用內部事件建立 DedupKey

DedupKey 應該建立在 DomainEvent 上，而不是 raw input 上。這能讓 HTTP、queue、timer 進來的同類事件共用去重規則。

 1func NewDedupKey(event DomainEvent, window time.Duration) DedupKey {
 2    return DedupKey{
 3        SubjectID: event.SubjectID,
 4        Type:      event.Type,
 5        SourceSet: sourceSet(event.Source),
 6        Window:    event.OccurredAt.UnixNano() / int64(window),
 7    }
 8}
 9
10func sourceSet(source EventSource) string {
11    switch source {
12    case SourceHTTPCallback, SourceQueue:
13        return "external_delivery"
14    case SourceTimer:
15        return "internal_scan"
16    default:
17        return string(source)
18    }
19}

OccurredAt 通常比 ReceivedAt 更適合事件語意去重。兩筆 retry 可能收到時間不同，但實際描述的發生時間相近；若使用收到時間，系統忙碌或網路延遲就會改變去重結果。

【判讀】哪些欄位不該放進 key

去重鍵的核心限制是不能包含每次都會變的欄位。這類欄位適合用於追蹤、除錯或觀測，不適合用於判斷是否同一事件。

不適合放進 key 的欄位：

request_id：每次 request 都可能不同。
received_at：取決於系統接收時間，不一定是事件語意。
delivery_attempt：重試次數本身就是重複事件的證據。
raw payload hash：欄位順序、metadata 或非語意欄位可能改變。
client IP、瀏覽器識別字串：代表傳輸脈絡，不代表事件本身。

適合放進 key 的欄位：

subject ID：事件作用的對象。
event type：發生了什麼事。
source set：資料權威或來源語意。
occurred time window：同一事件可接受的時間範圍。

【策略】時間窗口是取捨

時間窗口的核心作用是容忍短時間內的重送。窗口越短，越不容易誤殺不同事件；窗口越長，越能吸收延遲與 retry。

1const defaultDedupWindow = 30 * time.Second

窗口大小應該依事件語意決定：

事件類型	可用窗口	理由
account activated	1-5 分鐘	同一 account 短時間重複啟用通常是 retry
notification created	不一定適合時間窗口	使用者可能短時間建立多筆通知
job finished	30 秒-2 分鐘	job 完成事件通常只應發生一次
heartbeat received	不應去重成單一事件	heartbeat 本身就是週期訊號

時間窗口不是萬用答案。若事件本身允許短時間內多次發生，就需要更細的 subject 或 event ID，而不是把窗口調小到碰運氣。

【執行】Deduper 要保護共享 map

in-memory deduper 的核心責任是記住近期看過的 key，並在多 goroutine 下保持安全。只要 processor 可能同時處理事件，就需要 mutex 或單一 goroutine 擁有去重表。

 1type Deduper struct {
 2    mu      sync.Mutex
 3    seen    map[DedupKey]time.Time
 4    window  time.Duration
 5    expires time.Duration
 6}
 7
 8func NewDeduper(window, expires time.Duration) *Deduper {
 9    return &Deduper{
10        seen:    make(map[DedupKey]time.Time),
11        window:  window,
12        expires: expires,
13    }
14}
15
16func (d *Deduper) Seen(ctx context.Context, event DomainEvent) (bool, error) {
17    d.mu.Lock()
18    defer d.mu.Unlock()
19
20    key := NewDedupKey(event, d.window)
21    if _, ok := d.seen[key]; ok {
22        return true, nil
23    }
24
25    d.seen[key] = event.ReceivedAt
26    return false, nil
27}

ctx 在 memory 實作中可能用不到，但保留在 port 上能讓未來改成 Redis、資料庫或遠端服務時支援取消與逾時。

【執行】去重表必須清理

去重表的核心風險是無限制成長。只要把 key 放進 map，就必須定義 key 何時過期。

 1func (d *Deduper) Cleanup(now time.Time) {
 2    d.mu.Lock()
 3    defer d.mu.Unlock()
 4
 5    for key, seenAt := range d.seen {
 6        if now.Sub(seenAt) > d.expires {
 7            delete(d.seen, key)
 8        }
 9    }
10}

expires 通常應該大於 window。窗口決定兩筆事件是否可能被視為相同，過期時間決定 key 在記憶體中保留多久；兩者不是同一個概念。

【測試】用 table-driven test 固定語意

去重測試的核心目標是把「什麼算相同」寫成案例。這比只測 map 是否有資料更重要。

 1func TestDedupKey(t *testing.T) {
 2    base := time.Date(2026, 4, 22, 10, 0, 0, 0, time.UTC)
 3
 4    tests := []struct {
 5        name string
 6        a    DomainEvent
 7        b    DomainEvent
 8        same bool
 9    }{
10        {
11            name: "same subject type and window",
12            a: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base},
13            b: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceQueue, OccurredAt: base.Add(5 * time.Second)},
14            same: true,
15        },
16        {
17            name: "different subject",
18            a: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base},
19            b: DomainEvent{SubjectID: "acct_2", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base},
20            same: false,
21        },
22        {
23            name: "outside window",
24            a: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base},
25            b: DomainEvent{SubjectID: "acct_1", Type: EventAccountActivated, Source: SourceHTTPCallback, OccurredAt: base.Add(2 * time.Minute)},
26            same: false,
27        },
28    }
29
30    for _, tt := range tests {
31        t.Run(tt.name, func(t *testing.T) {
32            got := NewDedupKey(tt.a, time.Minute) == NewDedupKey(tt.b, time.Minute)
33            if got != tt.same {
34                t.Fatalf("same key = %v, want %v", got, tt.same)
35            }
36        })
37    }
38}

這個測試把來源融合、subject 差異與時間窗口都明確化。未來調整 key 時，測試會提醒你正在改變事件語意，而不只是改一個 struct。

本章不處理

本章先處理單一服務內的事件去重語意；跨節點一致性與 idempotency store，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 event normalization、processor 與 source priority；如果你要先回看語言教材，可以讀：

小結

事件去重是領域語意設計，不是 payload 比對。好的 DedupKey 會使用 subject、event type、source set 與合適的 occurred time window，並避免 request ID、收到時間與 raw payload hash 這類不穩定欄位。去重表還必須有清理策略，否則事件系統會用記憶體 leak 換取短期正確性。

5.2 WebSocket integration test

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

WebSocket integration test 的核心目標是驗證 client 與 server 透過真實連線互動後，協定行為是否正確。它比單元測試慢，但能覆蓋 HTTP upgrade、read/write pump、router、server message、push flow 與 cleanup。

本章目標

學完本章後，你將能夠：

用 httptest.Server 建立真實 WebSocket 測試入口
將 http:// 測試 URL 轉成 ws://
用 deadline 避免 read/write 永久卡住
驗證 subscribe、push、error response 與 cleanup
分辨 integration test 與 unit test 的責任邊界

【觀察】WebSocket 的錯誤常出現在元件交界

WebSocket 測試的核心困難是很多錯誤不在單一函式裡。Router 單元測試可能通過，但真實連線仍可能因為 upgrade path、read pump、write pump、send buffer 或 unregister 流程出錯。

Integration test 適合驗證這些交界：

client 能否成功 dial 到 /ws
server 是否接受 client action
subscribe 後是否收到 acknowledgement
server broadcast 是否能推到 client
client 關閉後 hub 是否清理連線
錯誤 action 是否回 error message 而不是斷線

這些不是每個單元測試都該覆蓋的內容。Integration test 的價值在於證明多個元件能透過真實協定協作。

【判讀】integration test 補的是協作信心

Integration test 的核心責任是覆蓋協定流程，不是取代所有規則測試。Router validation、topic normalization、dedup key、state transition 應主要用單元測試；WebSocket integration test 只挑關鍵端到端流程。

建議分工：

測試類型	負責內容
unit test	router、payload validation、subscription state、TrySend
integration test	dial、upgrade、read/write pump、server response、cleanup
race test	hub、client state、repository 的並發存取

如果每個 validation case 都啟動 WebSocket server，測試會變慢且失敗定位不清楚。Integration test 應少量、關鍵、穩定。

【執行】用 httptest.Server 建立真實入口

WebSocket integration test 的核心起點是 httptest.Server。它提供真實 HTTP server，不需要手動管理 port。

 1func TestWebSocketSubscribe(t *testing.T) {
 2    server := httptest.NewServer(newRouter())
 3    t.Cleanup(server.Close)
 4
 5    wsURL := "ws" + strings.TrimPrefix(server.URL, "http") + "/ws"
 6
 7    conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil)
 8    if err != nil {
 9        t.Fatalf("dial websocket: %v", err)
10    }
11    t.Cleanup(func() {
12        _ = conn.Close()
13    })
14}

httptest.NewServer 產生的是 http://127.0.0.1:port，WebSocket client 需要 ws://127.0.0.1:port/ws，所以常用字串轉換。

若 handler 需要 hub、router、fake repository，應在測試中明確組裝。這讓 integration test 的依賴可控。

【策略】測試 helper 應封裝連線樣板

Integration test 的核心樣板很多：建立 server、轉 URL、dial、設定 cleanup。可以用 helper 降低重複，但不要把協定斷言藏起來。

 1func newTestWebSocket(t *testing.T, handler http.Handler) (*websocket.Conn, *httptest.Server) {
 2    t.Helper()
 3
 4    server := httptest.NewServer(handler)
 5    t.Cleanup(server.Close)
 6
 7    wsURL := "ws" + strings.TrimPrefix(server.URL, "http") + "/ws"
 8    conn, _, err := websocket.DefaultDialer.Dial(wsURL, nil)
 9    if err != nil {
10        t.Fatalf("dial websocket: %v", err)
11    }
12    t.Cleanup(func() {
13        _ = conn.Close()
14    })
15
16    return conn, server
17}

Helper 負責重複 setup。測試本文仍應清楚寫出「送什麼 message、期待什麼 response」。

【執行】action 測試要檢查協定語意

Action 測試的核心流程是送 client message、讀 server message、檢查協定欄位。

 1func TestSubscribeActionReturnsAcknowledgement(t *testing.T) {
 2    conn, _ := newTestWebSocket(t, newRouter())
 3
 4    request := ClientMessage{
 5        Action: ActionSubscribeTopic,
 6        Data: mustJSON(t, SubscribeTopicRequest{
 7            Topic: "alerts",
 8        }),
 9    }
10
11    if err := conn.WriteJSON(request); err != nil {
12        t.Fatalf("write subscribe: %v", err)
13    }
14
15    response := readServerMessage(t, conn)
16    if response.Type != "topic_subscribed" {
17        t.Fatalf("response type = %q, want topic_subscribed", response.Type)
18    }
19    if response.Topic != "alerts" {
20        t.Fatalf("response topic = %q, want alerts", response.Topic)
21    }
22}

這個測試檢查的是協定語意，不只是連線沒有斷。Subscribe 的成功條件是 server 明確回覆訂閱成功。

【執行】每次讀取前設定 deadline

WebSocket integration test 的核心風險是永久卡住。每次等待 server message 前，都應設定 read deadline。

 1func readServerMessage(t *testing.T, conn *websocket.Conn) ServerMessage {
 2    t.Helper()
 3
 4    if err := conn.SetReadDeadline(time.Now().Add(2 * time.Second)); err != nil {
 5        t.Fatalf("set read deadline: %v", err)
 6    }
 7
 8    var response ServerMessage
 9    if err := conn.ReadJSON(&response); err != nil {
10        t.Fatalf("read server message: %v", err)
11    }
12    return response
13}

Deadline 是測試保護。若 server 沒有送出預期訊息，測試會在合理時間內失敗，而不是卡住整個測試套件。

Timeout 不應過短。CI 可能比本機慢，測試應給足合理緩衝，但仍要能快速暴露失敗。

【執行】推送測試要先建立可觀察觸發點

Server push 的核心測試流程是先讓 client 訂閱 topic，再從 server 端觸發 broadcast，最後讀取 client 收到的 message。

 1func TestSubscribedClientReceivesBroadcast(t *testing.T) {
 2    hub := NewHub()
 3    go hub.Run()
 4
 5    conn, _ := newTestWebSocket(t, newRouterWithHub(hub))
 6
 7    writeClientMessage(t, conn, ClientMessage{
 8        Action: ActionSubscribeTopic,
 9        Data:   mustJSON(t, SubscribeTopicRequest{Topic: "alerts"}),
10    })
11    _ = readServerMessage(t, conn)
12
13    hub.Broadcast("alerts", ServerMessage{
14        Type:  "notification",
15        Topic: "alerts",
16    })
17
18    pushed := readServerMessage(t, conn)
19    if pushed.Type != "notification" {
20        t.Fatalf("pushed type = %q, want notification", pushed.Type)
21    }
22}

這個測試證明 subscribe state、hub broadcast、write pump 能透過真實 connection 協作。若只想測 Broadcast 是否檢查 topic，應寫 hub unit test，不必走 WebSocket。

【策略】非同步清理用 eventually，不用固定 sleep

連線清理測試的核心問題是 cleanup 通常非同步發生。測試應等待可觀察條件，而不是固定 sleep。

 1func eventually(t *testing.T, timeout time.Duration, condition func() bool) {
 2    t.Helper()
 3
 4    deadline := time.Now().Add(timeout)
 5    for time.Now().Before(deadline) {
 6        if condition() {
 7            return
 8        }
 9        time.Sleep(10 * time.Millisecond)
10    }
11
12    t.Fatalf("condition was not met within %s", timeout)
13}

使用方式：

 1func TestClientIsRemovedAfterClose(t *testing.T) {
 2    hub := NewHub()
 3    conn, _ := newTestWebSocket(t, newRouterWithHub(hub))
 4
 5    eventually(t, time.Second, func() bool {
 6        return hub.ClientCount() == 1
 7    })
 8
 9    _ = conn.Close()
10
11    eventually(t, time.Second, func() bool {
12        return hub.ClientCount() == 0
13    })
14}

eventually 不是任意等待；它等待具體條件。失敗時，測試會指出 cleanup 沒發生，而不是把時間耗掉後仍然不清楚原因。

【判讀】error action 應測協定，不只測 log

WebSocket action 失敗的核心語意是單次 action 失敗，不一定代表連線失敗。Integration test 應確認 server 回 error message，並且連線仍可繼續使用。

 1func TestUnknownActionReturnsErrorMessage(t *testing.T) {
 2    conn, _ := newTestWebSocket(t, newRouter())
 3
 4    writeClientMessage(t, conn, ClientMessage{
 5        Action: "unknown_action",
 6    })
 7
 8    response := readServerMessage(t, conn)
 9    if response.Type != "error" {
10        t.Fatalf("response type = %q, want error", response.Type)
11    }
12}

若設計上 unknown action 應直接關閉連線，也應明確測出 close 行為。重點是協定行為要可驗證，不要只依賴 server log。

本章不處理

本章先處理單一 Go server 內的 WebSocket 協定協作；跨節點 fan-out 與壓力測試，會在下列章節再往外延伸：

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

和 Go 教材的關係

這一章承接的是 WebSocket handler、pump 與 heartbeat；如果你要先回看語言教材，可以讀：

小結

WebSocket integration test 應少量覆蓋關鍵端到端協定：dial、送 action、收 response、server push、錯誤回應與 cleanup。測試要使用真實 httptest.Server，每次 read 前設定 deadline，等待非同步清理時使用 eventually。單元測試負責大量規則，integration test 負責證明真實連線能把規則串起來。

6.2 健康檢查與診斷 endpoint

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

健康檢查與診斷 endpoint 的核心差異是使用者與風險不同。/health 給監控或負載平衡器判斷 process 是否活著，/ready 判斷是否應接流量，/debug/... 則給工程師排查問題且必須限制存取。

本章目標

學完本章後，你將能夠：

分辨 health、readiness、diagnostics 的語意
設計快速穩定的 /health
用 /ready 控制是否接新流量
條件啟用 pprof、runtime stats 等診斷入口
測試 status code 與 JSON response 合約

【觀察】所有狀態都塞進 health 會讓監控失真

Health endpoint 的核心風險是語意混亂。若 /health 同時檢查 process、database、queue、外部 API、cache、背景同步，任何依賴短暫波動都可能讓服務被判定死亡。

問題範例：

1/health
2  ├── process alive?
3  ├── database reachable?
4  ├── queue lag small?
5  ├── external API reachable?
6  └── background sync fresh?

這些問題不應全部塞進同一個 endpoint。Process 活著、可接流量、依賴降級、工程診斷，是不同操作訊號。

【判讀】health、ready、diagnostics 回答不同問題

操作 endpoint 的核心設計是每個 endpoint 只回答一個問題。

Endpoint	使用者	回答的問題	失敗影響
`/health`	process monitor	process 是否基本活著	可能重啟 process
`/ready`	load balancer	是否應接新流量	暫停導流
`/debug/...`	工程師	服務內部狀態如何	不應公開
`/metrics`	metrics collector	可聚合監控資料	監控缺資料

這樣切分後，某個外部依賴故障不一定要讓 process 被重啟；服務可能只是不 ready，或處於 degraded 狀態。

【執行】health endpoint 應簡單快速

Health endpoint 的核心責任是快速回答 process 是否能處理基本 HTTP request。它應該簡單、快速、穩定。

 1func HandleHealth(w http.ResponseWriter, r *http.Request) {
 2    if r.Method != http.MethodGet {
 3        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 4        return
 5    }
 6
 7    w.Header().Set("Content-Type", "application/json")
 8    w.WriteHeader(http.StatusOK)
 9    _, _ = w.Write([]byte(`{"status":"ok"}`))
10}

/health 不應執行昂貴查詢，也不應依賴大量下游服務。若健康檢查本身很慢，監控會把診斷工具變成新問題。

【執行】readiness 控制是否接流量

Readiness 的核心責任是回答「服務現在是否應該接新流量」。它可以檢查啟動狀態、必要依賴、shutdown 狀態。

 1type Readiness struct {
 2    ready        atomic.Bool
 3    shuttingDown atomic.Bool
 4}
 5
 6func (r *Readiness) Ready() bool {
 7    return r.ready.Load() && !r.shuttingDown.Load()
 8}
 9
10func HandleReady(readiness *Readiness) http.HandlerFunc {
11    return func(w http.ResponseWriter, r *http.Request) {
12        w.Header().Set("Content-Type", "application/json")
13
14        if !readiness.Ready() {
15            w.WriteHeader(http.StatusServiceUnavailable)
16            _, _ = w.Write([]byte(`{"status":"not_ready"}`))
17            return
18        }
19
20        w.WriteHeader(http.StatusOK)
21        _, _ = w.Write([]byte(`{"status":"ready"}`))
22    }
23}

服務啟動尚未完成、必要背景同步尚未就緒、或 graceful shutdown 已開始時，readiness 應回 503。Process 仍然活著，但不應接新流量。

【策略】dependency check 依照監控語意分層

依賴檢查的核心判斷是故障是否代表 process 應重啟。Database 暫時不可用不一定代表 process 壞掉；重啟可能無法修復，反而造成更多負載。

建議分層：

/health：只確認 process alive。
/ready：確認必要依賴是否足以接新流量。
/diagnostics/dependencies：提供工程師查看細節。

診斷 response 可以包含穩定欄位：

1{
2  "status": "degraded",
3  "dependencies": {
4    "database": "ok",
5    "queue": "lagging"
6  }
7}

監控應依賴 status code 與穩定欄位，工程師再用 body 細節診斷問題。自由文字可以輔助閱讀，但不應成為監控規則的依據。

【執行】diagnostics endpoint 要條件啟用

Diagnostics endpoint 的核心用途是提供工程師排查問題的資料。pprof、runtime metrics、internal queue length、goroutine count 都屬於這類。

 1func RegisterDiagnostics(mux *http.ServeMux, enabled bool) {
 2    if !enabled {
 3        return
 4    }
 5
 6    mux.HandleFunc("/debug/runtime", HandleRuntimeStats)
 7}
 8
 9func HandleRuntimeStats(w http.ResponseWriter, r *http.Request) {
10    var stats runtime.MemStats
11    runtime.ReadMemStats(&stats)
12
13    response := map[string]any{
14        "heap_alloc":  stats.HeapAlloc,
15        "num_gc":      stats.NumGC,
16        "goroutines":  runtime.NumGoroutine(),
17    }
18
19    _ = json.NewEncoder(w).Encode(response)
20}

Diagnostics 可能揭露內部狀態、記憶體資訊、goroutine 數量、路徑與部署細節，不應公開給一般使用者。若需要長期保留，至少應限制在內網、管理 port、認證或防火牆後。

【判讀】status code 是監控合約

健康檢查的核心合約是 status code。監控系統通常先看 HTTP code 與 timeout，不會理解複雜 body。

狀態	意義
`200 OK`	符合該 endpoint 的健康條件
`503 Service Unavailable`	暫時不可用或不應接流量
`405 Method Not Allowed`	呼叫方式錯誤
timeout	endpoint 無法在預期時間內回應

Body 可以提供人類可讀資訊，但不應讓監控依賴自由文字。若要機器讀取，使用穩定 JSON 欄位，例如 status、reason、dependencies。

【測試】endpoint 測試要鎖定 status code

Endpoint 測試的核心是驗證 status code 與穩定 JSON 欄位，而不是完整自由文字。

 1func TestReadyReturnsUnavailableWhenShuttingDown(t *testing.T) {
 2    readiness := &Readiness{}
 3    readiness.ready.Store(true)
 4    readiness.shuttingDown.Store(true)
 5
 6    req := httptest.NewRequest(http.MethodGet, "/ready", nil)
 7    rec := httptest.NewRecorder()
 8
 9    HandleReady(readiness).ServeHTTP(rec, req)
10
11    if rec.Code != http.StatusServiceUnavailable {
12        t.Fatalf("status = %d, want %d", rec.Code, http.StatusServiceUnavailable)
13    }
14}

Diagnostics endpoint 也應測 gate 關閉時不註冊或回 404，避免診斷入口不小心暴露。

本章不處理

本章先處理 health、readiness 與 diagnostics 的語意切分；Prometheus、OpenTelemetry 與平台設定，會在下列章節再往外延伸：

Go 進階：Observability pipeline、metrics 與 tracing

和 Go 教材的關係

這一章承接的是 pprof、runtime metrics 與 deploy readiness；如果你要先回看語言教材，可以讀：

小結

/health、/ready、diagnostics endpoint 解決不同問題。Health 檢查 process 基本可用性，readiness 控制是否接新流量，diagnostics 支援工程排查且應限制存取。Status code 是監控合約，JSON body 是補充細節；把這些訊號混在一起會讓操作判斷與安全邊界都變模糊。

7.2 Durable queue、outbox 與 idempotency

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

跨 process 事件傳遞的核心責任是讓事件在失敗、重試與重複投遞下仍維持可預期語意。Channel 只能處理單一 process 內的 backpressure ；[durable queue](/go-advanced/backend/knowledge-cards/durable-queue)、outbox 與 idempotency store 才能處理服務重啟、網路失敗與 consumer 重試。

本章目標

學完本章後，你將能夠：

理解 outbox 為什麼能避免半成功
分辨 domain dedup key 與 idempotency key 的用途
設計可重入的 consumer / processor
用 retry、DLQ 與回補流程處理失敗事件
把事件可靠性寫進資料結構，讓規則可以被程式與測試驗證

前置章節

後續撰寫方向

Outbox 如何避免「狀態已寫入，但事件沒送出」的半成功。
Idempotency key 如何和 domain dedup key 分工。
Consumer retry、dead-letter queue 與 poison message 如何設計處理流程。
At-least-once delivery 下，processor 如何保持可重入。
Queue lag、retry count、dead-letter count 應如何進入 log 與 metric。

【觀察】outbox 是把資料與事件綁在同一個 transaction

outbox 的核心概念是：先把業務狀態與待發事件一起寫進資料庫，再由獨立 publisher 把 outbox 內容送到 queue 或 broker。這樣即使 process 在寫完資料後當機，也不會丟掉事件。

典型流程是：

usecase 開 transaction。
寫入 domain data。
寫入 outbox record。
commit。
background publisher 讀出未送出的 outbox。
成功後把 outbox 標成已送出。

這個模型的重點是讓「至少會被發現並補送」成為可能。它承認跨 process 傳遞很難保證絕對只送一次，所以後續還要搭配 idempotency。

【判讀】idempotency 是跨 process 的必要邊界

只要事件可能重送，consumer 就要能承受重複訊息。idempotent processor 的核心是讓同一筆事件重複進來時，結果仍然穩定。

常見做法包括：

用 event ID 記錄已處理過的訊息
用 domain key 去重，讓同一個業務操作不會重複套用
用狀態機檢查 transition 是否已發生

【策略】DLQ 是流程的一部分

當事件重試失敗，dead-letter queue 要變成可處理的操作流程。你要知道：

為什麼失敗
要重試幾次
什麼錯誤可以直接放棄
什麼錯誤需要人工回補

如果沒有這些規則，DLQ 只會變成看不完的黑洞。

【執行】可重入 processor 的基本形式

可重入的核心要求是同一事件重跑時，不會把資料弄壞。簡化的處理流程通常長這樣：

 1func (p *Processor) Handle(ctx context.Context, evt Event) error {
 2    if p.store.Seen(evt.ID) {
 3        return nil
 4    }
 5
 6    if err := p.store.Apply(ctx, evt); err != nil {
 7        return err
 8    }
 9
10    return p.store.MarkSeen(ctx, evt.ID)
11}

實際實作時，Seen 與 MarkSeen 通常要跟業務狀態放在同一個一致性邊界裡，避免競態。

【延伸】queue lag 與 retry 需要被觀測

只要有 durable queue，就一定會有 backlog、retry 與 failure pattern。這些訊號應進入 log 與 metric，讓工程師知道是 producer 變慢、consumer 壞掉，還是下游依賴正在抖動。

本章不處理

本章不追求 exactly-once 的口號。教材重點會放在 Go 服務如何承認 at-least-once 的現實，並用 idempotent processor、outbox 與可觀測欄位降低風險。

和 Go 教材的關係

這一章承接 Go 的事件邊界與非阻塞送出；如果你要先回看語言教材，可以讀：

模組二：WebSocket 服務架構

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

WebSocket 服務的核心難點是連線建立後的長生命週期管理。HTTP upgrade 只是入口；每個 client 都有讀取、寫入、心跳、訂閱、推送佇列與清理流程。任何一個邊界不清楚，都可能造成 goroutine leak、concurrent write、慢 client 拖垮服務或訂閱狀態不一致。

本模組承接模組一的並發主題：read pump / write pump 對應 goroutine ownership，heartbeat 對應 select loop 與 ticker，send buffer 對應 backpressure，訂閱集合對應共享狀態與 copy boundary。

章節列表

章節	主題	關鍵收穫
2.1	read pump / write pump 模式	讓單一連線的讀取、寫入與清理責任可推理
2.2	heartbeat、deadline 與連線清理	用 ping/pong、deadline 與統一 unregister 偵測失效連線
2.3	訂閱模型與訊息路由	把 client action 轉成可測的 command 與訂閱狀態
2.4	慢客戶端與 send buffer 管理	用 bounded buffer、drop policy 與 byte budget 控制容量風險

本模組使用的範例主題

本模組使用虛構的即時通知服務作為範例。Client 可以訂閱 topic，server 會依 topic 推送 notification、status update 或 error message。

範例只用來展示 Go WebSocket 服務設計，不假設讀者正在維護任何特定專案。

本模組的 Go 核心概念

用一個 read pump 負責 client 輸入。
用一個 write pump 負責所有 WebSocket 寫入。
用 channel 作為 client send queue。
用 context、done channel 或 hub unregister 管理連線生命週期。
用 ticker 實作 heartbeat，但由 write pump 統一寫 ping。
用 mutex 或 hub event loop 保護訂閱狀態。
用 non-blocking send 保護 hub 不被慢 client 卡住。

學習重點

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

哪個 goroutine 可以讀 WebSocket，哪個 goroutine 可以寫 WebSocket
read pump、write pump、hub unregister 之間如何協作
heartbeat 失敗後應該走哪一條清理路徑
client action 應該在 router、usecase 還是 hub 裡處理
send buffer 滿載時應該丟棄、斷線、回錯或改用可靠儲存

章節粒度說明

WebSocket 章節依照連線生命週期拆分。Read/write pump、heartbeat、subscription routing、slow client 是四個不同責任；它們常在同一個 hub 或 client type 中互相呼叫，但教學上應分開建立模型。

如果只想處理單一問題，可以這樣查：

問題	優先閱讀
concurrent write 或讀寫責任混亂	read pump / write pump 模式
連線失效沒有被清理	heartbeat、deadline 與連線清理
action、payload、訂閱狀態混在一起	訂閱模型與訊息路由
慢 client 拖垮 hub	慢客戶端與 send buffer 管理

本模組不處理

本模組不討論 WebSocket 壓縮、水平擴展、跨節點廣播或完整身份驗證。這些都是實務重要主題，但必須先建立單一 Go process 內的連線生命週期與容量邊界；後續可接跨節點 WebSocket、presence 與重連協定。

先備知識

模組一：進階並發模式
Go 入門：標準庫 HTTP
知道 goroutine、channel、select、context 的基本用法

學習時間

預計 3-4 小時

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 成為可管理的服務行為。

2.3 訂閱模型與訊息路由

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

訂閱模型的核心目標是把 client action 轉成明確的連線狀態與回應訊息。WebSocket 是長連線，單次 action 失敗通常不應直接關閉連線；router 應把錯誤轉成可理解的 server message。

本章目標

學完本章後，你將能夠：

設計穩定的 client action envelope
把 router、handler、usecase 與 client state 分開
用訂閱集合表達 client 想收到的 topic
在 broadcast 前檢查訂閱狀態
測試 action routing、payload validation 與 error response

【觀察】client message 很容易變成臨時協定

WebSocket action 的核心風險是前後端快速加功能時，訊息格式變成一堆臨時欄位。若 action 名稱依賴按鈕、畫面或短期 UI 狀態，server 很快會累積難以維護的分支。

不穩定的訊息格式：

1{
2  "button": "watch",
3  "tab": "jobs",
4  "id": "topic_1"
5}

這種訊息描述 UI 發生什麼，不是描述 client 想對服務做什麼。服務端應該接收穩定 action，例如 subscribe_topic、unsubscribe_topic、list_subscriptions。

【判讀】action 是 client intent

Client action 的核心語意是「client 想做什麼」。它不是 domain event，因為它還沒被驗證、授權或套用規則。Domain event 表示已經發生的事，action 表示請求。

 1type ClientAction string
 2
 3const (
 4    ActionSubscribeTopic   ClientAction = "subscribe_topic"
 5    ActionUnsubscribeTopic ClientAction = "unsubscribe_topic"
 6    ActionListTopics       ClientAction = "list_topics"
 7)
 8
 9type ClientMessage struct {
10    Action ClientAction    `json:"action"`
11    Data   json.RawMessage `json:"data,omitempty"`
12}

外層 envelope 穩定，內層 Data 依 action 解析。這讓 read pump 可以先解析 envelope，router 再依 action 決定 payload 型別。

【策略】router 負責分派，不擁有全部規則

Router 的核心責任是把 action 分派到對應 handler。它應該知道有哪些 action，但不應把訂閱規則、權限檢查、資料查詢全部塞在一個巨大 switch 裡。

 1type Router struct {
 2    subscriptions *SubscriptionService
 3}
 4
 5func (r Router) Route(ctx context.Context, client *Client, message ClientMessage) error {
 6    switch message.Action {
 7    case ActionSubscribeTopic:
 8        return r.handleSubscribe(ctx, client, message.Data)
 9    case ActionUnsubscribeTopic:
10        return r.handleUnsubscribe(ctx, client, message.Data)
11    case ActionListTopics:
12        return r.handleListTopics(ctx, client)
13    default:
14        return fmt.Errorf("unknown action: %s", message.Action)
15    }
16}

switch 讓支援的 action 集中可見。真正的訂閱狀態修改可以交給 SubscriptionService 或 client method，避免 router 變成所有規則的聚集地。

【執行】payload validation 在 action 邊界完成

Payload validation 的核心責任是讓內部服務只收到有效 command。訂閱 topic 至少要檢查 JSON 格式、topic 是否空白、topic 名稱是否符合規則。

 1type SubscribeTopicRequest struct {
 2    Topic string `json:"topic"`
 3}
 4
 5type SubscribeTopicCommand struct {
 6    ClientID string
 7    Topic    string
 8}
 9
10func (r Router) handleSubscribe(ctx context.Context, client *Client, raw json.RawMessage) error {
11    var req SubscribeTopicRequest
12    if err := json.Unmarshal(raw, &req); err != nil {
13        return fmt.Errorf("decode subscribe request: %w", err)
14    }
15
16    topic := strings.TrimSpace(req.Topic)
17    if topic == "" {
18        return fmt.Errorf("topic is required")
19    }
20
21    cmd := SubscribeTopicCommand{
22        ClientID: client.ID(),
23        Topic:    topic,
24    }
25
26    return r.subscriptions.Subscribe(ctx, client, cmd)
27}

Request struct 是 wire format，command 是內部意圖。兩者分開後，JSON 命名、驗證錯誤與內部服務規則不會混在同一個型別。

【執行】訂閱集合是連線狀態

訂閱集合的核心語意是「這個 client 目前想收到哪些 topic」。它可以放在 client 上，也可以由 hub 集中保存；重點是 owner 要明確。

Client owner 版本：

 1type Client struct {
 2    id string
 3
 4    mu            sync.RWMutex
 5    subscriptions map[string]struct{}
 6}
 7
 8func (c *Client) Subscribe(topic string) {
 9    c.mu.Lock()
10    defer c.mu.Unlock()
11    c.subscriptions[topic] = struct{}{}
12}
13
14func (c *Client) Unsubscribe(topic string) {
15    c.mu.Lock()
16    defer c.mu.Unlock()
17    delete(c.subscriptions, topic)
18}
19
20func (c *Client) IsSubscribed(topic string) bool {
21    c.mu.RLock()
22    defer c.mu.RUnlock()
23    _, ok := c.subscriptions[topic]
24    return ok
25}

map[string]struct{} 是 Go 常見 set 表示法。若 read pump 修改訂閱，hub broadcast 讀取訂閱，就需要 lock 或把所有訂閱操作集中到 hub event loop。

【策略】訂閱狀態也需要 copy boundary

訂閱列表的核心風險是直接回傳 map 會暴露內部狀態。若需要列出目前訂閱，應回傳 slice 或 map copy。

 1func (c *Client) Subscriptions() []string {
 2    c.mu.RLock()
 3    defer c.mu.RUnlock()
 4
 5    topics := make([]string, 0, len(c.subscriptions))
 6    for topic := range c.subscriptions {
 7        topics = append(topics, topic)
 8    }
 9    sort.Strings(topics)
10    return topics
11}

回傳 sorted slice 讓測試更穩定，也避免呼叫端修改內部 map。排序不是業務必要條件，但對 API response 與測試可讀性有幫助。

【執行】成功與失敗都應回 server message

WebSocket action 的核心互動模式是 request-like，但連線不會因單次 action 結束。成功或失敗都應回一筆 server message，讓 client 能更新 UI 或顯示錯誤。

 1type ServerMessage struct {
 2    Type  string `json:"type"`
 3    Topic string `json:"topic,omitempty"`
 4    Error string `json:"error,omitempty"`
 5}
 6
 7func (s *SubscriptionService) Subscribe(ctx context.Context, client *Client, cmd SubscribeTopicCommand) error {
 8    client.Subscribe(cmd.Topic)
 9    ok := client.TrySend(ServerMessage{
10        Type:  "topic_subscribed",
11        Topic: cmd.Topic,
12    })
13    if !ok {
14        return ErrClientQueueFull
15    }
16    return nil
17}

若 action 失敗，read pump 或 router wrapper 可以把錯誤轉成 ServerMessage{Type: "error"}。不要只寫 server log，因為 client 需要知道該 action 沒有成功。

【執行】broadcast 前檢查訂閱

Broadcast 的核心規則是 producer 只產生 topic 與 message，hub 決定哪些 client 應該收到。訂閱邏輯不應散落在每個 producer 裡。

 1func (h *Hub) Broadcast(topic string, message ServerMessage) {
 2    for client := range h.clients {
 3        if !client.IsSubscribed(topic) {
 4            continue
 5        }
 6
 7        if ok := client.TrySend(message); !ok {
 8            h.unregister <- client
 9        }
10    }
11}

這段程式先檢查訂閱，再嘗試送出。若 client 的 send buffer 滿了，hub 可以 unregister 或採用其他慢 client 策略；下一章會專門處理。

【測試】router test 不需要真實 WebSocket

Router 的測試核心是 action 到行為的對應。它不需要真實 WebSocket connection，只需要 fake client 或檢查 client state。

 1func TestSubscribeActionAddsTopic(t *testing.T) {
 2    client := NewTestClient("client_1")
 3    router := Router{subscriptions: NewSubscriptionService()}
 4
 5    data := json.RawMessage(`{"topic":"alerts"}`)
 6    err := router.Route(context.Background(), client, ClientMessage{
 7        Action: ActionSubscribeTopic,
 8        Data:   data,
 9    })
10    if err != nil {
11        t.Fatalf("route subscribe: %v", err)
12    }
13
14    if !client.IsSubscribed("alerts") {
15        t.Fatalf("client should subscribe to alerts")
16    }
17}

Payload validation 也應獨立測：

 1func TestSubscribeActionRequiresTopic(t *testing.T) {
 2    client := NewTestClient("client_1")
 3    router := Router{subscriptions: NewSubscriptionService()}
 4
 5    err := router.Route(context.Background(), client, ClientMessage{
 6        Action: ActionSubscribeTopic,
 7        Data:   json.RawMessage(`{"topic":" "}`),
 8    })
 9    if err == nil {
10        t.Fatalf("empty topic should return error")
11    }
12}

WebSocket integration test 留給「真實 client/server 互動」；router 單元測試先確保協定語意正確。

本章不處理

本章先處理 action envelope 到 subscription 的路由與 ownership；授權、presence 與跨節點同步，會在下列章節延伸：

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

和 Go 教材的關係

這一章承接的是 WebSocket action、event fusion 與 handler boundary；如果你要先回看語言教材，可以讀：

小結

訂閱模型把 client action 轉成連線狀態與 server response。Action 是 client intent，不是 domain event；router 負責分派，payload validation 在邊界完成，訂閱集合要有明確 owner，broadcast 由 hub 統一檢查訂閱。這樣新增 action 或 topic 時，修改範圍會清楚且可測。

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 卡在哪個邊界。

4.3 Source of Truth：狀態邊界

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

Source of truth 的核心原則是系統中只有一個地方負責判定目前狀態。其他元件可以請求更新、讀取快照或訂閱變化，但不能各自保存一份會被當成真相的資料。

本章目標

學完本章後，你將能夠：

判斷狀態真相應該由哪個元件擁有
把狀態轉移集中在 repository 或 state owner
同步更新 current state 與 history
用 copy boundary 保護 slice、map、pointer
分辨 internal state、projection 與 response view

【觀察】狀態分散會讓系統失去真相

狀態分散的核心風險是每個元件都以為自己看到的是最新資料。handler 可能有 map，worker 可能有 cache，publisher 可能有最後推送狀態；當三者不一致時，系統很難回答「現在到底是什麼狀態」。

反模式示意：

1var handlerStates = map[string]string{}
2var workerStates = map[string]string{}
3var publisherLastSent = map[string]string{}

這三份資料可能都叫做 state，但只有一份應該是 source of truth。其他資料如果存在，應該明確標示為 cache、projection 或 delivery record，不能被當成狀態判斷依據。

【判讀】source of truth 是寫入權責

source of truth 的核心不是「資料存在哪裡」，而是「誰有權決定狀態如何轉移」。memory map、SQLite、PostgreSQL、Redis 都可以承擔儲存；真正的邊界是所有寫入都經過同一組規則。

 1type AccountStatus string
 2
 3const (
 4    AccountPending AccountStatus = "pending"
 5    AccountActive  AccountStatus = "active"
 6    AccountBlocked AccountStatus = "blocked"
 7)
 8
 9type AccountState struct {
10    ID        string
11    Status    AccountStatus
12    UpdatedAt time.Time
13}

AccountState 是 domain 狀態，不是 HTTP response。它應該表達系統內部真正需要維護的資料，而不是直接迎合某個 API 的輸出格式。

【策略】用明確方法集中狀態轉移

狀態轉移的核心規則是呼叫端不能直接改欄位。外部元件應該送進事件或 command，由 state owner 決定是否合法、如何更新、是否記錄 history。

 1type StateRepository struct {
 2    mu      sync.RWMutex
 3    records map[string]AccountRecord
 4}
 5
 6type AccountRecord struct {
 7    Current AccountState
 8    History []AccountState
 9}
10
11func NewStateRepository() *StateRepository {
12    return &StateRepository{
13        records: make(map[string]AccountRecord),
14    }
15}

repository 擁有 records map。其他元件不應取得這個 map 的 reference，也不應繞過 repository 修改狀態。

【執行】Apply 把事件轉成狀態變化

Apply 的核心責任是把 domain event 套用到 state。它是事件系統與狀態系統的交界。

 1func (r *StateRepository) Apply(ctx context.Context, event DomainEvent) error {
 2    r.mu.Lock()
 3    defer r.mu.Unlock()
 4
 5    record := r.records[event.SubjectID]
 6    next, err := transition(record.Current, event)
 7    if err != nil {
 8        return err
 9    }
10
11    record.Current = next
12    record.History = append(record.History, next)
13    r.records[event.SubjectID] = record
14
15    return nil
16}

這段程式在同一個 lock 內更新 current 與 history。讀者可以相信目前狀態與歷史紀錄來自同一筆事件，不會出現 current 已更新但 history 漏記的情境。

transition 可以是純函式：

 1func transition(current AccountState, event DomainEvent) (AccountState, error) {
 2    switch event.Type {
 3    case EventAccountActivated:
 4        return AccountState{
 5            ID:        event.SubjectID,
 6            Status:    AccountActive,
 7            UpdatedAt: event.OccurredAt,
 8        }, nil
 9    default:
10        return AccountState{}, fmt.Errorf("unsupported event type: %s", event.Type)
11    }
12}

純函式讓狀態規則更容易測試。repository 負責 concurrency 與保存，transition 負責 domain 規則。

【判讀】current、history、projection 是不同資料

狀態資料的核心分類是 internal state、history 與 projection。三者用途不同，不應混成同一個 struct 到處傳。

類型	角色	範例
internal state	系統判斷真相的資料	`AccountState`
history	狀態變化紀錄	`[]AccountState`
projection	查詢或 UI 需要的讀取模型	`AccountSummary`
response view	特定 API 的輸出格式	`accountResponse`

projection 可以從 state 與 history 組出來，但 projection 不應反過來成為狀態真相。API 需要新增欄位時，優先新增 response view 或 projection，不要直接污染 internal state。

【執行】查詢要回傳 copy

copy boundary 的核心目標是防止呼叫端修改 repository 內部資料。Go 的 slice、map、pointer 都可能讓內部狀態外洩。

 1func (r *StateRepository) Current(ctx context.Context, id string) (AccountState, bool, error) {
 2    r.mu.RLock()
 3    defer r.mu.RUnlock()
 4
 5    record, ok := r.records[id]
 6    if !ok {
 7        return AccountState{}, false, nil
 8    }
 9
10    return record.Current, true, nil
11}

AccountState 目前只有值型別欄位，直接回傳值即可。history 是 slice，必須複製：

1func (r *StateRepository) History(ctx context.Context, id string) ([]AccountState, error) {
2    r.mu.RLock()
3    defer r.mu.RUnlock()
4
5    history := r.records[id].History
6    result := make([]AccountState, len(history))
7    copy(result, history)
8    return result, nil
9}

若 state 內含 map、slice 或 pointer，還需要 deep copy。copy 有成本，但它是狀態邊界的保護；資料量大時應用分頁或 projection，不應直接暴露內部 slice。

【策略】projection 讓查詢需求不污染狀態

projection 的核心用途是服務讀取需求。列表頁、儀表板、即時推送可能需要不同欄位，這些需求不應全部塞進 domain state。

 1type AccountSummary struct {
 2    ID              string
 3    Status          AccountStatus
 4    LastChangedAt   time.Time
 5    HistoryCount    int
 6}
 7
 8func (r *StateRepository) Summary(ctx context.Context, id string) (AccountSummary, bool, error) {
 9    r.mu.RLock()
10    defer r.mu.RUnlock()
11
12    record, ok := r.records[id]
13    if !ok {
14        return AccountSummary{}, false, nil
15    }
16
17    return AccountSummary{
18        ID:            record.Current.ID,
19        Status:        record.Current.Status,
20        LastChangedAt: record.Current.UpdatedAt,
21        HistoryCount:  len(record.History),
22    }, true, nil
23}

projection 可以由 repository 即時計算，也可以由背景 worker 預先維護。選擇哪一種取決於讀取量、資料量與一致性要求；小型服務先即時計算通常更容易理解。

【判讀】mutex 與單一 goroutine 都能成為 state owner

狀態擁有權的核心要求是同一時間只有受控路徑能修改資料。mutex 是常見選擇，單一 goroutine 擁有 state 也是 Go 常見模式。

mutex 版本適合直接方法呼叫：

1repository.Apply(ctx, event)

單一 goroutine 版本適合事件流：

1type stateCommand struct {
2    event DomainEvent
3    reply chan error
4}

兩者都可以正確。選擇 mutex 時要小心 copy boundary；選擇 goroutine owner 時要設計 shutdown、reply channel 與 backpressure。不要為了使用 channel 而使用 channel，狀態模型簡單時 mutex 通常更直接。

【測試】狀態測試要覆蓋轉移與外洩

狀態邊界的測試目標是確認轉移一致、history 同步、呼叫端不能修改內部資料。

 1func TestHistoryReturnsCopy(t *testing.T) {
 2    repo := NewStateRepository()
 3    event := DomainEvent{
 4        ID:         "evt_1",
 5        Type:       EventAccountActivated,
 6        SubjectID:  "acct_1",
 7        OccurredAt: time.Now(),
 8        ReceivedAt: time.Now(),
 9    }
10
11    if err := repo.Apply(context.Background(), event); err != nil {
12        t.Fatalf("apply event: %v", err)
13    }
14
15    history, err := repo.History(context.Background(), "acct_1")
16    if err != nil {
17        t.Fatalf("history: %v", err)
18    }
19    history[0].Status = AccountBlocked
20
21    again, err := repo.History(context.Background(), "acct_1")
22    if err != nil {
23        t.Fatalf("history again: %v", err)
24    }
25    if again[0].Status != AccountActive {
26        t.Fatalf("repository state was modified through returned history")
27    }
28}

這個測試檢查的是邊界，不只是結果值。對 Go 服務來說，防止 slice/map 外洩是狀態設計的重要一環。

本章不處理

本章先處理單一服務內誰有寫入權責；資料庫 migration 與 CQRS，會在下列章節再往外延伸：

和 Go 教材的關係

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

小結

Source of truth 是寫入權責，不是某個特定資料庫。狀態轉移應集中在 repository 或 state owner，current 與 history 要在同一邊界更新，查詢要回傳 copy 或 projection。當狀態真相清楚時，handler、worker、publisher 都能保持簡單，系統也能更容易加入資料庫或新的讀取模型。

5.3 race condition 檢查

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

Race detector 的核心作用是找出測試執行期間發生的 data race。它能指出未同步讀寫同一份記憶體的位置，但不能取代 ownership、mutex、channel 與狀態邊界設計。

本章目標

學完本章後，你將能夠：

分辨 data race 與一般邏輯競爭
用 go test -race ./... 檢查並發路徑
寫出能觸發共享狀態讀寫的測試
依 race report 找到讀寫來源
選擇 mutex、channel owner 或 atomic 修正同步邊界

【觀察】並發 bug 常常不會穩定重現

Data race 的核心問題是測試可能偶爾通過、偶爾失敗，也可能完全不失敗但資料已經不安全。單次執行結果正確，不代表沒有未同步讀寫。

反模式：

1var count int
2
3func increment() {
4    count++
5}

count++ 不是原子操作。它包含讀取、加一、寫回。多個 goroutine 同時執行時，可能互相覆蓋結果，也可能被 race detector 偵測到未同步讀寫。

【判讀】data race 是未同步的並發讀寫

Data race 的核心定義是至少兩個 goroutine 同時存取同一份記憶體，其中至少一個是寫入，而且沒有同步保護。

觸發測試：

 1func TestIncrementRace(t *testing.T) {
 2    var wg sync.WaitGroup
 3
 4    for i := 0; i < 100; i++ {
 5        wg.Add(1)
 6        go func() {
 7            defer wg.Done()
 8            increment()
 9        }()
10    }
11
12    wg.Wait()
13}

一般 go test 不一定會失敗。go test -race 會在 runtime 偵測這類未同步讀寫，並輸出讀取與寫入發生的位置。

【執行】用 go test -race 跑到相關路徑

Race detector 的核心限制是只能檢查實際執行到的程式路徑。沒有被測試覆蓋的 goroutine、handler、repository 或 broadcast path，不會被它發現。

1go test -race ./...

這個指令會用 race detector 跑所有 package 的測試。它會比一般測試慢，但對含有 goroutine、共享 map、WebSocket hub、background worker 的服務非常重要。

若專案很大，可以先針對相關 package：

1go test -race ./internal/websocket ./internal/storage ./internal/worker

範圍縮小能讓日常執行更快，但合併前仍應跑完整路徑。

【策略】併發測試要讓共享狀態真的被同時讀寫

Race detector 的核心前提是測試要製造相關路徑。只建立 repository 卻不並發讀寫，race detector 沒有機會回報。

 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
17    wg.Wait()
18}

這個測試的主要斷言在「讓 race detector 執行共享 map 的讀寫路徑」。若 repository 忘記加 lock，-race 會指出問題。

【執行】WebSocket hub 也需要 race path

WebSocket hub 的核心並發風險是 client 註冊、取消註冊、訂閱變更與 broadcast 可能同時發生。測試應讓這些路徑交錯執行。

 1func TestHubConcurrentBroadcastAndUnregister(t *testing.T) {
 2    hub := NewHub()
 3    clients := make([]*Client, 0, 100)
 4
 5    for i := 0; i < 100; i++ {
 6        client := NewTestClient(fmt.Sprintf("client_%d", i), 8)
 7        client.Subscribe("alerts")
 8        hub.clients[client] = struct{}{}
 9        clients = append(clients, client)
10    }
11
12    var wg sync.WaitGroup
13    wg.Add(2)
14
15    go func() {
16        defer wg.Done()
17        for i := 0; i < 100; i++ {
18            hub.Broadcast("alerts", ServerMessage{Type: "notification"})
19        }
20    }()
21
22    go func() {
23        defer wg.Done()
24        for _, client := range clients {
25            hub.unregisterClient(client)
26        }
27    }()
28
29    wg.Wait()
30}

這個測試是否需要 lock，取決於 hub 的設計。如果 hub 保證所有操作都在單一 event loop 中執行，測試就應該透過 channel 操作，而不是直接呼叫未同步方法。測試要符合 ownership 設計，不應製造不被 API 允許的並發。

【判讀】race report 要看讀寫兩端

Race report 的核心資訊是兩個位置：一端讀或寫，另一端寫。修正時不要只看最後一行，要找出是哪個共享資料缺少同步。

典型報告會包含：

1WARNING: DATA RACE
2Read at 0x...
3  example.com/app.(*UserRepository).Find()
4
5Previous write at 0x...
6  example.com/app.(*UserRepository).Save()

這表示 Find 和 Save 同時碰到同一份資料，且缺少同步。修正方向是在 repository owner 補上 mutex、channel ownership 或其他同步邊界。

【策略】修正方式要對應狀態形狀

修正 data race 的核心選擇是建立正確同步邊界。常見方法有 mutex、channel owner、atomic。

方法	適用情境	注意事項
mutex	多方法讀寫同一份 map/slice/state	lock 要保護完整不變式
channel owner	狀態修改可集中成事件 loop	要設計 reply、shutdown、backpressure
atomic	單一數值 counter 或 flag	不適合複雜狀態

Mutex 範例：

 1type Counter struct {
 2    mu    sync.Mutex
 3    value int
 4}
 5
 6func (c *Counter) Inc() {
 7    c.mu.Lock()
 8    defer c.mu.Unlock()
 9    c.value++
10}
11
12func (c *Counter) Value() int {
13    c.mu.Lock()
14    defer c.mu.Unlock()
15    return c.value
16}

鎖應該屬於擁有狀態的型別，並保護一個清楚的不變條件。只為了讓 race detector 安靜而到處加鎖，會讓 ownership 分散，後續仍然難以判斷資料一致性。

【判讀】race-free 不代表行為正確

Race detector 的核心邊界是它只找 data race，不保證並發邏輯正確。沒有 data race 的程式仍可能 deadlock、漏訊息、順序錯誤、重複 close 或違反資料語意。

例如：

1select {
2case client.send <- message:
3default:
4    // drop
5}

這段程式可能沒有 data race，但「queue full 時丟訊息」是否正確是服務語意問題。Race detector 不會告訴你該丟、該斷線、還是該寫可靠 queue。

因此並發測試要分成兩層：

用 go test -race 找未同步記憶體存取。
用行為測試檢查 channel close、queue full、context cancel、cleanup、timeout。

【測試】把 race check 納入固定流程

Race check 的核心價值來自重複執行。只在出事後手動跑，效果有限。

建議流程：

1go test ./...
2go test -race ./...

日常開發可以先跑相關 package，提交前或 CI 跑完整 race suite。若 race suite 太慢，至少讓含有 hub、repository、worker、client state 的 package 固定跑 -race。

本章不處理

本章先處理共享 state、channel ownership 與 goroutine lifecycle 的 race 風險；lock-free 與完整 memory model，會在下列章節再往外延伸：

和 Go 教材的關係

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

小結

go test -race 是 Go 並發服務的基本安全網，但它只檢查測試執行到的 data race。你仍然需要設計清楚的 state owner、lock boundary、channel ownership 與行為測試。Race-free 不是正確性的全部；它只是可靠性的第一層檢查。

6.3 結構化日誌欄位設計

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

結構化日誌欄位的核心目標是讓 log 可查詢、可聚合、可追蹤。Message 給人讀，欄位給系統查；重要資訊應放在穩定欄位，不應只藏在自由文字裡。

本章目標

學完本章後，你將能夠：

設計穩定 log schema
用 layer、request_id、event_type、reason 支援查詢
區分 message 與 structured fields 的責任
避免重複記錄同一個錯誤
避免把敏感資料寫進 log

【觀察】自由文字 log 很難查詢

Log 設計的核心問題是事故發生時需要快速查詢。若所有資訊都在 message 裡，查詢只能依賴模糊字串。

不穩定 log：

1logger.Info("event accepted for user 123 request abc")

這行給人看可以，但系統很難穩定查 request_id=abc 或 user_id=123。不同工程師改字句後，查詢就可能失效。

結構化 log：

1logger.Info("event accepted",
2    "layer", "http",
3    "request_id", requestID,
4    "user_id", userID,
5    "event_type", event.Type,
6)

Message 描述發生什麼事，欄位提供可查詢資料。這是 log schema 的基本分工。

【判讀】log schema 是查詢合約

Log schema 的核心規則是欄位名稱與值集合要穩定。request_id、requestID、rid 混用會讓查詢與儀表板變得困難。

常用欄位：

欄位	用途
`layer`	問題發生在哪個系統層
`request_id`	串起單次 HTTP request
`event_id`	串起事件處理流程
`event_type`	聚合某類 domain event
`client_id`	查 WebSocket client 行為
`topic`	查訂閱或推送範圍
`reason`	聚合失敗原因
`error`	保存錯誤文字

欄位不需要很多，但要一致。穩定欄位能讓除錯從「讀一堆文字」變成「查一組條件」。

【執行】layer 表示發生位置

layer 的核心用途是標示 log 來自哪個系統層，協助工程師快速縮小問題範圍。

1logger.Warn("queue full",
2    "layer", "worker",
3    "queue", "events",
4    "reason", "buffer_full",
5)

常見 layer：

http
websocket
worker
repository
runtime
diagnostics

名稱不需要多，但應穩定。若 worker、background、job_runner 混用，查詢就會變麻煩。

【策略】correlation ID 串起一次流程

Correlation ID 的核心目標是把同一次請求或同一個事件流串起來。HTTP request 常用 request_id，背景事件可以用 event_id 或 trace_id。

1func WithRequestLog(r *http.Request, logger *slog.Logger) *slog.Logger {
2    requestID := r.Header.Get("X-Request-ID")
3    if requestID == "" {
4        requestID = uuid.NewString()
5    }
6
7    return logger.With("request_id", requestID)
8}

後續 handler、service、repository 都使用帶有 request_id 的 logger。查詢單次流程時，不需要靠時間範圍猜哪些 log 相關。

Correlation ID 不應包含敏感資料。它是追蹤用識別碼，不是使用者資料容器。

【執行】reason 欄位讓失敗可統計

reason 的核心用途是把錯誤原因變成可聚合分類。Message 可以給人讀，reason 給查詢與統計使用。

1logger.Warn("reject event",
2    "layer", "http",
3    "reason", "invalid_payload",
4    "event_type", event.Type,
5)

穩定 reason 可以回答「最近一小時最多的拒絕原因是什麼」。如果原因只寫在 message 中，查詢會依賴模糊字串比對。

Reason 值應像 enum 一樣維持小集合，例如：

invalid_payload
queue_full
permission_denied
timeout
client_disconnected
dependency_unavailable

reason 應維持小集合分類，完整錯誤應放在 error 欄位。這樣監控可以穩定聚合原因，工程師仍能從錯誤欄位取得診斷細節。

【判讀】錯誤只在負責處理的邊界記一次

錯誤日誌的核心風險是同一個錯誤被每一層都記一次。這會放大噪音，讓事故時很難看出真正的失敗點。

反模式：

1logger.Error("repository failed", "error", err)
2return fmt.Errorf("save notification: %w", err)

上層又記一次：

1logger.Error("request failed", "error", err)

較清楚的做法是底層 wrap error，上層在決定 response 或重試策略的邊界記錄一次：

1if err := service.Create(ctx, cmd); err != nil {
2    logger.Warn("create notification failed",
3        "layer", "http",
4        "reason", reasonOf(err),
5        "error", err,
6    )
7    writeError(w, err)
8    return
9}

底層若有必要補充脈絡，優先透過 error wrapping 或 structured error，而不是每層都 Error log。

【策略】敏感資料不進 log

Log 欄位設計的核心安全邊界是只記錄診斷必要資料。token、密碼、完整 cookie、完整個資與機密 payload 都屬於應排除資料；結構化 log 很容易被集中保存與搜尋，敏感資料一旦進入 log，清理成本很高。

可以記錄：

1logger.Info("user login",
2    "user_id", user.ID,
3)

應排除：

1logger.Info("user login",
2    "password", password,
3    "token", token,
4)

若需要診斷 payload，可記錄長度、hash、欄位是否存在，而不是完整內容。

1logger.Debug("payload received",
2    "payload_bytes", len(body),
3    "payload_sha256", checksum(body),
4)

所有會被收集或保存的 log 都應遵守同一套資料保護規則。Debug log 也會進入檔案、集中式 log 或診斷封包，因此不能把它當成敏感資料的例外通道。

【測試】log 欄位可以用 handler 驗證

Log schema 的測試核心是確認重要欄位存在，避免未來重構時消失。

 1func TestLogAttrsForEvent(t *testing.T) {
 2    event := DomainEvent{
 3        ID:        "evt_1",
 4        Type:      "notification.created",
 5        SubjectID: "notification_1",
 6    }
 7
 8    attrs := LogAttrsForEvent(event)
 9
10    if !hasAttr(attrs, "event_id", "evt_1") {
11        t.Fatalf("event_id attr missing")
12    }
13    if !hasAttr(attrs, "event_type", "notification.created") {
14        t.Fatalf("event_type attr missing")
15    }
16}

不需要測整行 log 字串。測穩定欄位即可，message 文字可以保留一定調整空間。

本章不處理

本章先處理 Go 服務內部的 structured log schema；集中式平台、欄位標準與隱私治理，會在下列章節再往外延伸：

Go 進階：Observability pipeline、metrics 與 tracing

和 Go 教材的關係

這一章承接的是 structured recording、event log 與 observability pipeline；如果你要先回看語言教材，可以讀：

小結

結構化日誌的價值在於穩定欄位：layer 定位層級，request_id 串起請求，event_id 串起事件，event_type 支援聚合，reason 支援失敗分類。Message 給人讀，欄位給系統查。好的 log schema 能讓除錯從猜測變成查詢，同時避免敏感資料外洩與錯誤重複記錄。

7.3 跨節點 WebSocket、presence 與重連協定

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

跨節點 WebSocket 的核心責任是把連線狀態、訂閱狀態與推送路徑從單一記憶體 hub 延伸到多台 server。單一 process 內的 read pump、write pump、heartbeat 與 slow client 策略仍然有效，但跨節點後還需要 broker、presence store、重連協定與授權邊界。

本章目標

學完本章後，你將能夠：

理解單節點 hub 為什麼不夠
看懂 presence store 與 broker 在系統中的角色
設計 reconnect 後的補資料流程
分辨訂閱路由、連線管理與授權邊界
讓多台 server 在語意上看起來像同一個訊息系統

前置章節

後續撰寫方向

多台 server 如何知道某個 topic 的訂閱者在哪些節點。
Presence store 如何記錄 client online、offline 與最後活動時間。
Broker fan-out 如何和每個節點本地 send buffer 策略銜接。
Client reconnect 如何使用 cursor、last event ID 或 snapshot 補資料。
Topic ACL 與 subscription authorization 應放在 router、usecase 還是 gateway。

【觀察】跨節點 WebSocket 的核心問題是狀態協調

WebSocket 協定解決的是單一連線的雙向通訊，但跨節點之後，真正麻煩的是狀態分散在多台 server。某個 client 可能連到 A 節點，但它關注的 topic 事件卻從 B 節點產生，這時就需要能夠路由、轉送與補資料。

所以跨節點 WebSocket 的問題不只是「能不能推送」，而是：

這個 client 現在在哪台 server
它訂閱了哪些 topic
推送失敗後要不要重送
重新連線後要從哪裡補回遺漏事件

【判讀】presence store 是操作查詢

presence store 的用途是讓系統知道某個 client 或節點目前大概在線上還是離線。它通常是操作性資料，不一定是業務真相。

常見欄位包括：

client ID
node ID
connected at
last seen
subscription keys

這類資料要允許過期與清理，因為斷線、網路抖動與 crash 都可能讓狀態暫時不準。

【策略】reconnect 一定要有補資料設計

只靠重新連上 WebSocket 並不能保證使用者不漏訊息。當連線中斷時，常見的補資料方式有：

last event ID
cursor / offset
snapshot + delta

選哪一種，取決於你的事件是否可排序、是否可回放，以及業務能容忍多大的缺口。

【執行】推送路徑通常要分三層

跨節點場景下，推送路徑常見會分成：

事件產生端把訊息交給 broker 或 routing layer。
節點收到後，交給本機 hub / connection manager。
write pump 再把訊息送到單一 client。

這樣可以維持單一寫入者原則，避免多個 goroutine 同時寫 WebSocket。

【延伸】授權應該在進入路由前就處理

Topic ACL 要在訂閱建立時就確認這個 client 是否有資格加入。這能減少不必要的 fan-out 與敏感資料外流。

本章不處理

本章不會選定特定 broker 或 presence database。重點是先讓跨節點責任可見，再依服務需求選擇 Redis、NATS、Kafka、PostgreSQL 或其他基礎設施。

和 Go 教材的關係

這一章承接的是 WebSocket 連線架構與事件路由；如果你要先回看語言教材，可以讀：

模組三：Runtime 與效能診斷

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

Runtime 診斷的核心目標是用資料判斷服務壓力來源。Go 服務長時間運行後，問題常出現在 heap 成長、GC 壓力、goroutine 數量、WebSocket buffer 堆積、JSON 配置與共享狀態保留；診斷流程應先看趨勢，再用 profile 定位來源。

本模組承接前面的並發、WebSocket 與測試可靠性：如果 goroutine lifecycle、send buffer、repository copy boundary 沒設計好，runtime 訊號會在 heap profile、goroutine profile、CPU profile 或 allocation profile 中反映出來。

章節列表

章節	主題	關鍵收穫
3.1	GC 與 memory limit	理解 heap、GOGC、memory limit 與 runtime metrics 的關係
3.2	pprof 基礎診斷流程	用 heap、goroutine、CPU、trace profile 定位壓力來源
3.3	goroutine leak 偵測	從 stack pattern 回到 context、close、deadline 與 ticker lifecycle
3.4	資料結構與 allocation 壓力	區分必要 copy、安全邊界與可優化熱路徑配置

本模組使用的範例主題

本模組使用虛構的即時通知服務作為範例。範例包含 WebSocket client lifecycle、background worker、repository list、JSON push payload 與 cache。

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

本模組的 Go 核心概念

用 runtime.ReadMemStats 或 runtime/metrics 觀察 heap、GC 與 goroutine 趨勢。
用 debug.SetMemoryLimit 給 runtime 軟性記憶體目標。
用 pprof 分析 heap、goroutine、CPU、block、mutex 與 trace。
用 goroutine profile 找出卡在 channel、network read、ticker、mutex 的路徑。
用 alloc_space 與 inuse_space 區分配置壓力與保留記憶體。
用資料結構設計降低不必要 allocation，但保留必要 copy boundary。

學習重點

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

記憶體問題是 GC 壓力、長期保留，還是短暫尖峰
什麼情境適合調整 memory limit，什麼情境應該找 leak
heap、goroutine、CPU、trace 各自回答什麼問題
goroutine leak 應回到哪個 lifecycle 邊界修
allocation 優化何時值得做，何時會破壞安全邊界

本模組不處理

本模組不討論分散式 tracing 平台、完整監控系統或雲端特定 profiler。這些工具可以接在本模組之後；本模組先建立 Go runtime 原生訊號與 pprof 的診斷思路。後續可接 Observability pipeline、metrics 與 tracing。

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

2.4 慢客戶端與 send buffer 管理

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

慢客戶端管理的核心問題是單一 client 的讀取速度可能低於 server 推送速度。若 send buffer 沒有上限，慢 client 會把訊息堆在記憶體裡；若 hub 使用 blocking send，慢 client 會拖住所有 client。

本章目標

學完本章後，你將能夠：

分辨慢 client 對 hub、write pump、記憶體的影響
用 bounded send channel 限制單一 client 的排隊量
設計 queue full 時的 drop、disconnect、coalesce 策略
在必要時用 byte budget 管理大型 payload
測試 send buffer 滿載與 client unregister 行為

【觀察】慢 client 會把局部問題變成全域問題

慢 client 的核心風險是它不只影響自己。若 hub broadcast 時對每個 client 使用 blocking send，其中一個 client 的 send channel 滿了，hub 就可能卡住，其他 client 也收不到訊息。

反模式：

1func (h *Hub) Broadcast(message ServerMessage) {
2    for client := range h.clients {
3        client.send <- message
4    }
5}

這段程式看起來保證送達，但實際上把整個 hub 的可用性綁在最慢的 client 上。只要一個 client 不讀，所有 broadcast 都可能停住。

【判讀】send channel 是每個 client 的容量邊界

Send channel 的核心責任是作為單一 client 的輸出佇列。它必須有容量上限，否則 server 會替慢 client 無限制保存訊息。

 1const sendBufferSize = 64
 2
 3type Client struct {
 4    id   string
 5    send chan ServerMessage
 6}
 7
 8func NewClient(id string) *Client {
 9    return &Client{
10        id:   id,
11        send: make(chan ServerMessage, sendBufferSize),
12    }
13}

Buffer 的目的只是吸收短暫尖峰，不是讓 client 長期落後。若 client 長期消費速度低於推送速度，任何有限 buffer 都會滿。

【策略】滿載策略取決於訊息語意

慢 client 滿載的核心決策是訊息能不能遺失。不同資料類型需要不同策略。

訊息類型	常見策略	理由
即時狀態 snapshot	可丟棄舊訊息或 coalesce	最新狀態比每個中間狀態重要
action result	優先送達，滿載時可斷線	client 需要知道操作結果
診斷 log stream	可取樣或丟棄	資料量大，通常不是唯一真相
金流、訂單、稽核事件	不應只靠 WebSocket	需要可靠儲存或可重播來源

WebSocket send buffer 不應承擔資料可靠性。若訊息不能遺失，可靠性應放在資料庫、queue 或 event log，WebSocket 只負責即時通知。

【執行】non-blocking send 保護 hub

Hub 的核心保護是 broadcast 時不被單一 client 阻塞。TrySend 可以讓 hub 立即知道該 client 是否已滿載。

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

Hub 可以把滿載 client 送進 unregister：

 1func (h *Hub) Broadcast(topic string, message ServerMessage) {
 2    for client := range h.clients {
 3        if !client.IsSubscribed(topic) {
 4            continue
 5        }
 6
 7        if ok := client.TrySend(message); !ok {
 8            h.unregister <- client
 9        }
10    }
11}

這種策略犧牲慢 client，保護整體服務。對即時通知服務來說，讓慢 client 重連並重新取得 snapshot，通常比讓所有 client 等它更合理。

【策略】drop newest、drop oldest、disconnect 是不同語意

Queue full 策略的核心差異是保留哪一筆資料，以及是否繼續維持連線。

策略	行為	適用情境
drop newest	新訊息不進 queue	舊訊息仍有價值
drop oldest	移除舊訊息，保留最新	狀態型更新
disconnect	關閉 client，要求重連	client 已明顯跟不上
coalesce	合併多筆更新成一筆	topic 最新狀態可覆蓋

Drop oldest 範例：

 1func (c *Client) TrySendLatest(message ServerMessage) bool {
 2    select {
 3    case c.send <- message:
 4        return true
 5    default:
 6    }
 7
 8    select {
 9    case <-c.send:
10    default:
11    }
12
13    select {
14    case c.send <- message:
15        return true
16    default:
17        return false
18    }
19}

這段程式表示「新狀態比舊狀態重要」。它不適合 action result 或不可遺失事件，因為它會主動丟掉尚未送出的舊訊息。

【策略】byte budget 比 message count 更接近記憶體風險

Message count 的核心限制是每筆訊息大小不同。64 筆小訊息和 64 筆大型 JSON payload 的記憶體成本差很多；當 payload 大小差異明顯時，可以加上 byte budget。

 1type Client struct {
 2    send      chan ServerMessage
 3    sendBytes int64
 4    maxBytes  int64
 5}
 6
 7func (c *Client) TrySend(message ServerMessage) bool {
 8    size := int64(message.Size())
 9    if atomic.AddInt64(&c.sendBytes, size) > c.maxBytes {
10        atomic.AddInt64(&c.sendBytes, -size)
11        return false
12    }
13
14    select {
15    case c.send <- message:
16        return true
17    default:
18        atomic.AddInt64(&c.sendBytes, -size)
19        return false
20    }
21}

Write pump 成功取出並寫出訊息後，必須扣回 byte budget：

1func (c *Client) markSent(message ServerMessage) {
2    atomic.AddInt64(&c.sendBytes, -int64(message.Size()))
3}

Byte budget 更接近記憶體風險，但也更複雜。只有在訊息大小差異大、或服務連線數高時才值得加入；小型服務先用固定 buffer 通常足夠。

【判讀】write pump 慢不一定是 client 的錯

慢寫入的核心原因可能在 client，也可能在 server。Client 網路慢、瀏覽器停住、行動裝置休眠會造成慢寫；server payload 太大、序列化太慢、單次寫入沒有 deadline 也會造成問題。

排查方向：

send buffer 長期接近滿載
write deadline 錯誤增加
單筆 message size 過大
broadcast 頻率超過 client 消費能力
某些 topic 推送量異常高

queue full 的歸因應同時檢查 client 與 server 端訊號。若所有 client 都慢，通常是 server 推送量、payload 大小或下游網路策略出問題。

【策略】滿載要有觀測欄位

慢 client 策略的核心要求是可觀測。若系統選擇 drop 或 disconnect，應記錄足夠欄位讓工程師知道原因。

 1func (h *Hub) handleFullClient(client *Client, topic string) {
 2    metrics.Inc("websocket_client_send_full")
 3    h.logger.Warn("websocket client send buffer full",
 4        "client_id", client.ID(),
 5        "topic", topic,
 6        "send_queue_len", len(client.send),
 7        "send_queue_cap", cap(client.send),
 8    )
 9    h.unregister <- client
10}

Log 用來追單次事件，metric 用來看趨勢。若滿載數量突然增加，可能是某個 topic 推送量上升，也可能是 client 版本或網路環境改變。

【測試】滿載測試要先填滿 buffer

慢 client 測試的核心是直接建立滿載條件。容量為 1 的 channel 加上預先填滿的資料，可以穩定製造 queue full；sleep 只是在等待排程運氣。

 1func TestTrySendReturnsFalseWhenBufferFull(t *testing.T) {
 2    client := &Client{
 3        id:   "client_1",
 4        send: make(chan ServerMessage, 1),
 5    }
 6    client.send <- ServerMessage{Type: "first"}
 7
 8    ok := client.TrySend(ServerMessage{Type: "second"})
 9    if ok {
10        t.Fatalf("TrySend should return false when buffer is full")
11    }
12}

Hub unregister 行為也可以測：

 1func TestBroadcastUnregistersFullClient(t *testing.T) {
 2    hub := NewHub()
 3    client := NewTestClient("client_1", 1)
 4    client.Subscribe("alerts")
 5    client.send <- ServerMessage{Type: "existing"}
 6    hub.clients[client] = struct{}{}
 7
 8    hub.Broadcast("alerts", ServerMessage{Type: "new"})
 9
10    select {
11    case got := <-hub.unregister:
12        if got != client {
13            t.Fatalf("unregister client mismatch")
14        }
15    default:
16        t.Fatalf("full client should be unregistered")
17    }
18}

這類測試直接驗證服務策略：client 滿載時，hub 不阻塞，而是走指定降級路徑。

本章不處理

本章先處理單一 server 內的慢 client 與 send buffer 邊界；跨節點 fan-out 與持久化同步，會在下列章節延伸：

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

和 Go 教材的關係

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

小結

慢客戶端是 WebSocket 服務的容量控制問題。每個 client 的 send buffer 必須有上限，hub broadcast 不應被單一 client 阻塞，queue full 策略要符合訊息語意。必要時可加入 byte budget，但更重要的是明確決定 drop、disconnect、coalesce 或可靠儲存，並用 log、metric、測試讓降級行為可見。

3.4 資料結構與 allocation 壓力

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

Allocation 分析的核心目標是區分必要的安全複製與可優化的重複配置。Go 服務中很多配置來自 slice 成長、map/list 複製、JSON marshal、buffer 建立與 WebSocket payload；優化前要先確認配置是否位於熱路徑，且不能破壞狀態邊界。

本章目標

學完本章後，你將能夠：

理解 allocation 如何增加 GC 壓力
分辨必要 copy boundary 與不必要重複配置
用預配置降低 slice 成長成本
判斷 JSON marshal 與 WebSocket payload 的重用邊界
用 pprof 的 alloc_space 與 inuse_space 決定優化方向

【觀察】allocation 壓力會放大 GC 成本

Allocation 的核心影響是增加 heap 成長速度，進而增加 GC 工作量。即使物件很快被回收，大量短命配置仍可能造成 CPU 與 latency 壓力。

常見熱路徑：

每次 WebSocket broadcast 都對每個 client 重新 marshal。
每次 API list 都建立大型 slice。
每次 repository 查詢都 copy 大型 map。
每次 log 都組大量臨時欄位。
每次 encode 都建立新的 bytes.Buffer。

不是所有 allocation 都要消除。診斷重點是找出高頻、可避免、且不破壞邊界的配置。

【判讀】預配置解決的是成長成本

Slice 預配置的核心用途是讓底層 array 成長符合預期。若結果長度可預估，應用 make 設定容量。

未預配置：

1func BuildNames(users []User) []string {
2    var names []string
3    for _, user := range users {
4        names = append(names, user.Name)
5    }
6    return names
7}

預配置：

1func BuildNames(users []User) []string {
2    names := make([]string, 0, len(users))
3    for _, user := range users {
4        names = append(names, user.Name)
5    }
6    return names
7}

這不是微優化。若這段程式在高頻 list API、background projection 或 broadcast path 中執行，預配置可以減少反覆擴容與 copy。

【判讀】copy boundary 是必要成本

安全複製的核心目的是保護內部可變狀態。Repository 回傳資料時 copy slice 或 map，會增加 allocation，但能避免外部突變與 data race。

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

這個 allocation 是狀態邊界的成本。優化前要先確認它是否真的是瓶頸，不能只因為 profile 看到配置就移除 copy。

若列表很大且讀取頻繁，應考慮分頁、projection、snapshot cache 或只回傳必要欄位。不要為了省配置而直接暴露內部 map。

【策略】大型 list 優先改資料形狀

大型 list allocation 的核心問題常常是 API 一次回太多資料。若每次請求都複製整個 repository，配置與延遲都會隨資料量線性成長。

可選策略：

策略	適用情境	代價
分頁	使用者只需要部分資料	API 需要 cursor 或 offset
projection	只需要摘要欄位	要維護讀取模型
snapshot cache	讀多寫少	要處理快取失效
incremental update	WebSocket 推送最新變化	client 要能合併狀態

優化資料形狀通常比取消 copy 更安全。Copy boundary 保護正確性，資料形狀決定每次 copy 的成本。

【執行】JSON marshal 是 WebSocket 常見配置來源

JSON 序列化的核心成本是把 Go 資料結構轉成 bytes。高頻 WebSocket 推送若對每個 client 反覆 marshal 同一份 message，會造成大量短命配置。

反模式：

1for _, client := range clients {
2    payload, err := json.Marshal(message)
3    if err != nil {
4        return err
5    }
6    client.SendBytes(payload)
7}

同一份 message 可以先 marshal 一次：

1payload, err := json.Marshal(message)
2if err != nil {
3    return err
4}
5
6for _, client := range clients {
7    client.SendBytes(payload)
8}

這個優化的前提是 payload 被視為只讀。Send path 不應修改傳入的 bytes；若某個 client 需要修改，就應在該 client 邊界 copy，而不是讓共享 payload 被改動。

【判讀】bytes 重用要先定義所有權

Bytes 重用的核心風險是共享 slice 被修改。[]byte 是可變資料，傳給多個 client 時要明確規定它只讀。

可以用型別或註解表達語意：

1type EncodedMessage []byte
2
3func (c *Client) SendEncoded(message EncodedMessage) bool {
4    return c.TrySend(ServerMessage{
5        Encoded: message,
6    })
7}

這不能從型別上完全禁止修改，但能讓 API 語意更清楚。真正保護仍靠 ownership 規則、測試與 code review。

若無法保證下游不修改，就必須 copy：

1func CloneBytes(input []byte) []byte {
2    output := make([]byte, len(input))
3    copy(output, input)
4    return output
5}

效能優化不能建立在模糊的可變資料共享上。

【策略】sync.Pool 只適合已證明的熱路徑

sync.Pool 的核心用途是複用高頻、短命、可重建的暫存物件。它可以降低配置，但會增加所有權複雜度。

 1var bufferPool = sync.Pool{
 2    New: func() any {
 3        return new(bytes.Buffer)
 4    },
 5}
 6
 7func Encode(value any) ([]byte, error) {
 8    buf := bufferPool.Get().(*bytes.Buffer)
 9    defer bufferPool.Put(buf)
10    buf.Reset()
11
12    if err := json.NewEncoder(buf).Encode(value); err != nil {
13        return nil, err
14    }
15
16    output := append([]byte(nil), buf.Bytes()...)
17    return output, nil
18}

這裡仍然 copy 出 output，因為 buf 會被放回 pool。若直接回傳 buf.Bytes()，呼叫端拿到的 slice 可能在 pool 重用後被覆寫。

不要一開始就使用 sync.Pool。先用 pprof 證明配置是瓶頸，再評估 pool 是否值得承擔額外複雜度。

【判讀】inuse 與 alloc 回答不同問題

Heap profile 的核心判讀是分清 inuse_space 與 alloc_space。

1go tool pprof http://localhost:8080/debug/pprof/heap
2go tool pprof -alloc_space http://localhost:8080/debug/pprof/heap

指標	問題	常見修正
`inuse_space` 高	現在誰保留記憶體	cache 淘汰、釋放引用、限制 buffer
`alloc_space` 高	誰累積配置最多	預配置、重用、減少 marshal、改資料形狀

若 alloc_space 高但 inuse_space 不高，代表配置很多但大多被回收，問題可能是 GC 壓力。若 inuse_space 持續上升，代表資料被長期保留，應檢查 cache、map、slice、goroutine reference 或 send buffer。

【策略】allocation 優化要保留正確性邊界

Allocation 優化的核心底線是不能破壞狀態安全。以下做法通常不可接受：

為了省 copy，直接回傳 repository 內部 map。
為了省 bytes，讓多個 client 共享可修改 payload。
為了省 allocation，把 buffer 放回 pool 後仍回傳其底層 slice。
為了少建立 struct，把 request DTO 和 domain state 混用。

較安全的優化順序：

用 pprof 確認熱點。
預配置已知大小的 slice/map。
減少重複 marshal。
改 API 資料形狀，例如分頁或 projection。
最後才考慮 sync.Pool。

這個順序先處理低風險、高可讀性的改動，再處理高複雜度工具。

【測試】優化後要補邊界測試

Allocation 優化的測試核心是確保共享資料沒有被外部修改。若你重用 bytes、snapshot 或 pooled buffer，要補測試保護 ownership。

例如 repository list 仍要回傳 copy：

 1func TestListUsersReturnsCopy(t *testing.T) {
 2    repo := NewUserRepository()
 3    ctx := context.Background()
 4    _ = repo.Save(ctx, User{ID: "user_1"})
 5
 6    users, err := repo.ListUsers(ctx)
 7    if err != nil {
 8        t.Fatalf("list users: %v", err)
 9    }
10    users[0].ID = "changed"
11
12    again, err := repo.ListUsers(ctx)
13    if err != nil {
14        t.Fatalf("list users again: %v", err)
15    }
16    if again[0].ID != "user_1" {
17        t.Fatalf("repository data was modified through returned slice")
18    }
19}

這種測試能防止未來為了省 allocation 而移除必要 copy。

本章不處理

本章先處理熱路徑上的配置與資料形狀；更大範圍的序列化與 payload 策略，會在下列章節再往外延伸：

和 Go 教材的關係

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

小結

Allocation 優化要先判斷配置是否必要。保護狀態的 copy 是合理成本，高頻熱路徑的重複配置才是優先目標。JSON marshal、slice 成長、map/list 複製與 buffer 建立都是常見來源；用 pprof 區分 inuse_space 與 alloc_space 後，再決定預配置、分頁、projection、payload 重用或 sync.Pool。

4.4 多來源 event 融合

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

事件融合的核心目標是讓不同來源的同類事件進入同一套內部規則。HTTP callback、queue message、timer scan 與檔案 reader 都只是輸入方式；進入 processor 前，它們應該被轉成一致的 DomainEvent。

本章目標

學完本章後，你將能夠：

分辨來源差異與 domain 規則差異
為不同來源設計 adapter 與 normalize
用 channel 或直接呼叫收斂事件入口
為突發流量設計 backpressure 策略
決定錯誤應回給上游、重試、丟棄或記錄

【觀察】來源增加後規則容易分裂

事件來源增加的核心風險是每個來源各自實作一套處理規則。HTTP handler 有一套 validation，queue consumer 有一套 retry 判斷，timer worker 又有一套狀態更新；最後同一種 domain event 在不同入口產生不同結果。

反模式示意：

1HTTP callback ──> validate A ──> update state A
2queue message ──> validate B ──> update state B
3timer scan    ──> validate C ──> update state C

這種結構的問題是 domain 規則分裂。新增來源時，應該新增 adapter，不應複製 processor。

【判讀】來源差異應限制在 adapter

事件融合的核心原則是來源差異停在 adapter 與 normalizer。來源可以有不同 authentication、ack、HTTP status、payload 格式與重試語意；但轉成 DomainEvent 後，processor 應該面對一致模型。

目標結構：

1HTTP callback ─┐
2queue message ─┼─> normalize ─> DomainEvent ─> processor
3timer scan    ─┘

這個結構讓新增來源變成局部擴充。你新增一個 adapter 與 normalize test，而不是複製 validation、dedup、repository update 與 publish 邏輯。

【策略】先定義每個來源的責任

來源設計的核心動作是明確寫出每個 adapter 對上游的承諾。不同來源的錯誤回應方式不同，但進入 processor 的事件語意應一致。

來源	adapter 責任	失敗回應
HTTP callback	decode JSON、驗證簽章、normalize	回 4xx/5xx
queue consumer	decode message、控制 ack/nack、normalize	ack、nack 或 retry
timer scan	讀取本地狀態、產生內部事件	記錄錯誤或下次再掃
file reader	讀取增量資料、normalize	記錄 offset 或停下

表格是設計工具。若某一列寫不清楚，代表 adapter 與 processor 的邊界還不清楚。

【執行】HTTP adapter 轉成 DomainEvent

HTTP adapter 的核心責任是處理 HTTP 協定與外部 payload。它可以回應 status code，但不應直接決定狀態如何更新。

 1type HTTPEventHandler struct {
 2    processor *EventProcessor
 3    now       func() time.Time
 4}
 5
 6func (h HTTPEventHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 7    var raw RawHTTPEvent
 8    if err := json.NewDecoder(r.Body).Decode(&raw); err != nil {
 9        writeError(w, http.StatusBadRequest, "invalid_json")
10        return
11    }
12
13    event, err := NormalizeHTTPEvent(raw, h.now())
14    if err != nil {
15        writeError(w, http.StatusBadRequest, "invalid_event")
16        return
17    }
18
19    if err := h.processor.Process(r.Context(), event); err != nil {
20        writeError(w, http.StatusServiceUnavailable, "event_not_accepted")
21        return
22    }
23
24    w.WriteHeader(http.StatusAccepted)
25}

StatusAccepted 表示事件已被系統接收，不一定表示所有下游推送都完成。若 API 語意要求同步完成，就需要在文件與測試中明確定義成功條件。

【執行】queue adapter 控制 ack/nack

queue adapter 的核心責任是把 message lifecycle 對應到 processor 結果。processor 不應知道 ack、nack 或 delivery tag。

 1type QueueMessage struct {
 2    Body        []byte
 3    Ack         func() error
 4    Nack        func(requeue bool) error
 5}
 6
 7type QueueConsumer struct {
 8    processor *EventProcessor
 9    now       func() time.Time
10}
11
12func (c QueueConsumer) Handle(ctx context.Context, msg QueueMessage) error {
13    event, err := NormalizeQueueMessage(msg.Body, c.now())
14    if err != nil {
15        return msg.Nack(false)
16    }
17
18    if err := c.processor.Process(ctx, event); err != nil {
19        return msg.Nack(true)
20    }
21
22    return msg.Ack()
23}

這段程式把 queue 的重試決策留在 adapter。對 processor 來說，事件只是一筆 DomainEvent；對 queue 來說，錯誤需要轉成 ack/nack 策略。

【策略】共用 channel 需要 backpressure

共用 channel 的核心用途是把多個來源收斂到同一個處理 loop。它不是必要架構，但在多來源、突發流量或單一 worker 順序處理時很有用。

1events := make(chan DomainEvent, 1024)

channel 一旦有容量限制，就必須設計滿載策略。沒有滿載策略的 channel 只會把問題延後到 goroutine 堆積或 request 卡住。

 1func EnqueueEvent(ctx context.Context, events chan<- DomainEvent, event DomainEvent) error {
 2    select {
 3    case events <- event:
 4        return nil
 5    case <-ctx.Done():
 6        return ctx.Err()
 7    default:
 8        return ErrEventQueueFull
 9    }
10}

HTTP handler 遇到 ErrEventQueueFull 可以回 503。queue consumer 可以 nack 並 requeue。timer scan 可以跳過本輪。不同來源的上游回應不同，但進入 channel 的事件模型相同。

【執行】processor loop 擁有消費節奏

processor loop 的核心責任是決定事件如何被消費與停止。它應該接受 context，並在 shutdown 時停止讀取新事件。

 1type EventLoop struct {
 2    processor *EventProcessor
 3    events    <-chan DomainEvent
 4    logger    *slog.Logger
 5}
 6
 7func (l EventLoop) Run(ctx context.Context) error {
 8    for {
 9        select {
10        case <-ctx.Done():
11            return ctx.Err()
12        case event := <-l.events:
13            if err := l.processor.Process(ctx, event); err != nil {
14                l.logger.Error("process event failed",
15                    "event_type", event.Type,
16                    "subject_id", event.SubjectID,
17                    "error", err,
18                )
19            }
20        }
21    }
22}

正式實作還要處理 channel close。若事件來源會關閉 channel，讀取時應使用 event, ok := <-l.events；若 channel 由長生命週期服務持有，通常由 context 控制 shutdown。

【判讀】錯誤策略要依來源與資料語意決定

錯誤策略的核心問題是「失敗後誰能重送，重送是否安全」。HTTP、queue、timer 的答案不同。

錯誤位置	HTTP callback	queue message	timer scan
decode 失敗	400，不重試	nack(false) 或 dead-letter	記錄錯誤
normalize 失敗	400，不重試	nack(false) 或 dead-letter	記錄錯誤
processor 暫時失敗	503，可重試	nack(true)	下次再掃
duplicate event	202 或 204	ack	忽略
publisher 失敗	視語意而定	視語意而定	視語意而定

錯誤策略不能只看技術來源，也要看資料語意。若事件已經成功更新狀態但即時推送失敗，HTTP 是否要回錯取決於 API 是否承諾推送已完成。

【策略】觀測欄位要跨來源一致

事件融合後的 log 與 metric 也應使用共同欄位。這讓你能跨 HTTP、queue、timer 比較同一類事件的行為。

 1func LogAttrsForEvent(event DomainEvent) []slog.Attr {
 2    return []slog.Attr{
 3        slog.String("event_id", event.ID),
 4        slog.String("event_type", string(event.Type)),
 5        slog.String("event_source", string(event.Source)),
 6        slog.String("subject_id", event.SubjectID),
 7        slog.Time("occurred_at", event.OccurredAt),
 8        slog.Time("received_at", event.ReceivedAt),
 9    }
10}

adapter 可以額外記錄 HTTP path、queue name 或 timer name，但共同欄位應該來自 DomainEvent。這樣排查問題時，讀者不用先知道事件從哪個來源進來。

【測試】融合測試要驗證同類事件走同一規則

多來源測試的核心目標是確認不同 adapter 產生同一種 DomainEvent，並且 processor 對它們套用同一組規則。

 1func TestHTTPAndQueueNormalizeToSameDomainEvent(t *testing.T) {
 2    receivedAt := time.Date(2026, 4, 22, 10, 0, 10, 0, time.UTC)
 3
 4    httpEvent, err := NormalizeHTTPEvent(RawHTTPEvent{
 5        EventID:   "evt_1",
 6        AccountID: "acct_1",
 7        EventName: "activated",
 8        Timestamp: "2026-04-22T10:00:00Z",
 9    }, receivedAt)
10    if err != nil {
11        t.Fatalf("normalize http event: %v", err)
12    }
13
14    queueEvent, err := NormalizeQueueMessage([]byte(`{
15        "id":"evt_1",
16        "subject":"acct_1",
17        "type":"account.activated",
18        "occurred_at":"2026-04-22T10:00:00Z"
19    }`), receivedAt)
20    if err != nil {
21        t.Fatalf("normalize queue event: %v", err)
22    }
23
24    if httpEvent.Type != queueEvent.Type || httpEvent.SubjectID != queueEvent.SubjectID {
25        t.Fatalf("sources should normalize to same domain semantics")
26    }
27}

這個測試不是要求兩個 event 完全相同。Source 可以不同；重點是 domain semantics 一致，processor 才能共用規則。

本章不處理

本章先處理多來源事件如何在單一服務內融合；queue driver、outbox 與 tracing，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是多來源 adapter、normalize 與 processor 的路線；如果你要先回看語言教材，可以讀：

小結

事件融合的核心是把來源差異限制在 adapter 與 normalizer，讓 processor 只面對一致的 DomainEvent。HTTP、queue、timer 可以有不同的 backpressure 與錯誤回應，但不應複製 domain 規則。當來源增加時，系統應該增加 adapter，而不是增加另一套狀態更新流程。

5.4 table-driven test 的設計邊界

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

Table-driven test 的核心邊界是每張表只描述一個行為維度。它能降低重複並清楚列出案例，但不適合把多種 setup、多種執行方式與多種斷言硬塞進同一個測試。

本章目標

學完本章後，你將能夠：

判斷什麼行為適合 table-driven test
設計欄位少、意圖清楚的測試表
發現 table test 膨脹成迷你框架的訊號
拆分 validation、repository error、integration flow
寫出能定位失敗情境的子測試名稱

【觀察】table-driven test 很容易被濫用

Table-driven test 的核心風險是「減少重複」被誤解成「所有案例都塞進一張表」。當表格開始同時控制 HTTP method、request body、repository 狀態、WebSocket client、expected log、expected event，測試就會變成難懂的迷你框架。

失控表格示意：

 1tests := []struct {
 2    name          string
 3    method        string
 4    body          string
 5    setupRepo     bool
 6    setupClient   bool
 7    queueFull     bool
 8    wantStatus    int
 9    wantMessage   string
10    wantEvent     bool
11    wantLog       bool
12}{
13    // many unrelated cases
14}

這種表格看似統一，實際上混合了 HTTP validation、repository error、client queue full、event emission、log assertion。讀者必須同時理解多個系統層，才能看懂單一案例。

【判讀】好表格描述同一個行為維度

好的 table-driven test 的核心特徵是所有案例共享相同 setup、相同執行方式、相同斷言方式。表格只改變資料，不改變測試流程。

 1func TestNormalizeTopic(t *testing.T) {
 2    tests := []struct {
 3        name  string
 4        input string
 5        want  string
 6    }{
 7        {name: "trim spaces", input: " alerts ", want: "alerts"},
 8        {name: "lowercase", input: "ALERTS", want: "alerts"},
 9        {name: "empty", input: "", want: ""},
10    }
11
12    for _, tt := range tests {
13        t.Run(tt.name, func(t *testing.T) {
14            got := NormalizeTopic(tt.input)
15            if got != tt.want {
16                t.Fatalf("NormalizeTopic(%q) = %q, want %q", tt.input, got, tt.want)
17            }
18        })
19    }
20}

這張表只測 topic normalization。每個案例都只有 input 和 want，失敗時也能立刻看出是哪個 normalization 規則壞了。

【策略】表格欄位越多，越要懷疑測試邊界

Table 欄位的核心警訊是大量欄位只被少數案例使用。這通常表示不同測試目的被合併在一起。

拆分判斷：

現象	問題	建議
很多 `setupX bool`	setup 不一致	拆成不同測試
很多 `wantX bool`	斷言目標不一致	拆成不同測試
loop 內大量 `if tt...`	測試流程不一致	拆表或改成具名測試
案例名稱很長仍說不清	行為維度太多	回到單一行為
helper 隱藏主要斷言	可讀性下降	讓斷言留在測試本文

表格不是越通用越好。測試的第一責任是讓失敗可定位，不是消除所有重複。

【執行】validation 適合 table test

Validation 的核心特徵是輸入和輸出形狀一致，因此很適合 table-driven test。

 1func TestValidateSubscribeRequest(t *testing.T) {
 2    tests := []struct {
 3        name    string
 4        request SubscribeTopicRequest
 5        wantErr bool
 6    }{
 7        {
 8            name:    "valid topic",
 9            request: SubscribeTopicRequest{Topic: "alerts"},
10            wantErr: false,
11        },
12        {
13            name:    "empty topic",
14            request: SubscribeTopicRequest{Topic: ""},
15            wantErr: true,
16        },
17        {
18            name:    "blank topic",
19            request: SubscribeTopicRequest{Topic: "   "},
20            wantErr: true,
21        },
22    }
23
24    for _, tt := range tests {
25        t.Run(tt.name, func(t *testing.T) {
26            err := ValidateSubscribeRequest(tt.request)
27            if (err != nil) != tt.wantErr {
28                t.Fatalf("error = %v, wantErr %v", err, tt.wantErr)
29            }
30        })
31    }
32}

這張表只問一件事：request 是否有效。它不測 WebSocket connection、不測 hub、不測 repository，因此案例可以保持簡潔。

【執行】狀態轉移也適合 table test

狀態轉移的核心特徵是輸入狀態、事件、期待輸出狀態。只要流程一致，就適合 table-driven test。

 1func TestJobTransition(t *testing.T) {
 2    tests := []struct {
 3        name    string
 4        current JobStatus
 5        event   EventType
 6        want    JobStatus
 7        wantErr bool
 8    }{
 9        {
10            name:    "pending starts",
11            current: JobPending,
12            event:   EventJobStarted,
13            want:    JobRunning,
14        },
15        {
16            name:    "running finishes",
17            current: JobRunning,
18            event:   EventJobFinished,
19            want:    JobSucceeded,
20        },
21        {
22            name:    "finished cannot start again",
23            current: JobSucceeded,
24            event:   EventJobStarted,
25            wantErr: true,
26        },
27    }
28
29    for _, tt := range tests {
30        t.Run(tt.name, func(t *testing.T) {
31            got, err := Transition(tt.current, tt.event)
32            if (err != nil) != tt.wantErr {
33                t.Fatalf("error = %v, wantErr %v", err, tt.wantErr)
34            }
35            if err == nil && got != tt.want {
36                t.Fatalf("status = %s, want %s", got, tt.want)
37            }
38        })
39    }
40}

這張表的欄位都服務同一個行為：job status transition。若未來要測 repository 寫入失敗，應另開測試，不要塞進這張表。

【判讀】不同 setup 應拆成不同測試

測試拆分的核心原則是 setup 不同，通常就不是同一張表。HTTP validation、repository error、client queue full 都需要不同環境。

較清楚的拆法：

 1func TestSubscribeValidation(t *testing.T) {
 2    // 只測 request validation
 3}
 4
 5func TestSubscribeAddsTopic(t *testing.T) {
 6    // 只測成功訂閱後 client state
 7}
 8
 9func TestSubscribeReturnsErrorWhenClientQueueFull(t *testing.T) {
10    // 只測 send buffer 滿載時的錯誤語意
11}

這些測試可能有少量重複，但每個測試的失敗原因更清楚。測試重複一點可以接受；測試意圖混在一起會讓維護成本更高。

【策略】helper 只包樣板，不包判斷

Test helper 的核心責任是降低重複 setup，不應隱藏主要斷言。讀者應能在測試本文看到這個測試到底在驗證什麼。

可以包的樣板：

1func mustJSON(t *testing.T, value any) json.RawMessage {
2    t.Helper()
3    data, err := json.Marshal(value)
4    if err != nil {
5        t.Fatalf("marshal json: %v", err)
6    }
7    return data
8}

不建議包成這樣：

1func assertSubscribeScenario(t *testing.T, tt subscribeScenario) {
2    // setup HTTP, setup WebSocket, setup repository,
3    // execute action, check response, check logs, check events
4}

後者把測試主要邏輯藏進 helper。表格看起來短，但讀者必須跳到 helper 才知道每個欄位如何影響流程。

【執行】子測試名稱要描述情境

子測試名稱的核心作用是讓失敗輸出可定位。名稱應描述情境，不應只寫編號或重複函式名稱。

1tests := []struct {
2    name string
3    // ...
4}{
5    {name: "missing topic"},
6    {name: "unknown action"},
7    {name: "queue full returns unavailable"},
8}

go test 輸出會包含 TestValidateSubscribeRequest/missing_topic 這類資訊。當 CI 失敗時，讀者能先知道哪個情境壞了，再看 got/want 差異。

命名應該描述輸入情境或規則，不需要寫成完整句子，也不要只寫 case 1。

【測試】table test 本身也要保持可讀

Table-driven test 的核心完成標準是讀者能掃過表格就理解規則。若必須讀整個 loop 才懂欄位意義，表格設計就不夠清楚。

自檢問題：

這張表是否只測一個行為？
每個欄位是否幾乎每個案例都用得到？
測試 loop 裡是否有大量條件分支？
子測試名稱是否能定位失敗情境？
got/want 斷言是否直接留在測試本文？

任一題答否，先考慮拆測試，而不是加更多欄位。

本章不處理

本章先處理單一行為的多組資料案例；property-based、fuzz 與 snapshot 測試，會在下列章節再往外延伸：

Go 進階：CI、fuzz、load test 與 chaos testing

和 Go 教材的關係

這一章承接的是 test case 設計、handler boundary 與 command 驗證；如果你要先回看語言教材，可以讀：

小結

Table-driven test 適合同一個行為的多組資料，不適合混合多種 setup 與斷言。欄位膨脹、loop 裡大量 if tt...、helper 隱藏主要判斷，都是拆表訊號。好的測試表讓案例更清楚，而不是把測試變成迷你框架。

6.4 版本偵測與 feature gate

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

Feature gate 的核心目標是在外部能力、部署環境或版本不同時，讓服務保留可預期行為。它明確管理功能何時啟用、關閉時如何降級、錯誤時如何回報。

本章目標

學完本章後，你將能夠：

用 config struct 集中載入 feature gate
把外部版本偵測轉成 capability
為 gate 關閉時定義降級、回錯或延後處理策略
避免在程式各處直接讀環境變數
同時測試 feature 開與關兩條路徑

【觀察】新功能上線需要可控行為

Feature gate 的核心需求來自生產環境差異。新功能可能只在部分部署環境可用，外部依賴可能版本不同，某些診斷入口只應在內網啟用，某些即時能力需要先灰度。

沒有 gate 時常見問題：

新功能只能一次性全開或全關。
部署環境不支援時服務直接失敗。
測試只能覆蓋預設路徑。
問題發生時無法快速降級。
程式各處用環境變數判斷，行為難以推理。

Feature gate 的目的是讓行為決策集中、可測、可回滾。

【判讀】feature gate 是行為合約

Feature gate 的核心語意是控制某段行為是否啟用，以及未啟用時系統要做什麼。它不只是 if，而是一個操作合約。

1type Features struct {
2    RealtimePush bool
3    Diagnostics  bool
4    Pprof        bool
5}

開關名稱應描述功能，而不是描述臨時任務。RealtimePush 比 NewCode 更能長期維護；Diagnostics 比 DebugStuff 更清楚。

Gate 應在應用啟動時集中載入，再傳給需要的元件。不要在程式各處反覆直接讀環境變數，否則測試與推理都會變困難。

【執行】集中載入 feature config

Feature config 的核心責任是把環境變數、設定檔或啟動參數轉成明確資料。

1func LoadFeaturesFromEnv() Features {
2    return Features{
3        RealtimePush: os.Getenv("FEATURE_REALTIME_PUSH") == "1",
4        Diagnostics:  os.Getenv("APP_DIAGNOSTICS") == "1",
5        Pprof:        os.Getenv("APP_PPROF") == "1",
6    }
7}

組裝時傳入元件：

 1func main() {
 2    features := LoadFeaturesFromEnv()
 3
 4    mux := http.NewServeMux()
 5    RegisterDiagnostics(mux, features.Diagnostics)
 6
 7    publisher := NewPublisher(PublisherConfig{
 8        RealtimeEnabled: features.RealtimePush,
 9    })
10
11    _ = publisher
12}

這樣功能測試可以直接建構 Features，不必依賴全域環境變數。環境變數解析只需要在 LoadFeaturesFromEnv 的測試中覆蓋。

【判讀】版本偵測要轉成能力

版本偵測的核心原則是不要讓整個程式到處比較版本字串。應把外部版本轉成 capability，內部只判斷能力。

 1type Capabilities struct {
 2    SupportsStreaming bool
 3    SupportsMetadata  bool
 4}
 5
 6func DetectCapabilities(version semver.Version) Capabilities {
 7    return Capabilities{
 8        SupportsStreaming: version.GTE(semver.MustParse("2.0.0")),
 9        SupportsMetadata:  version.GTE(semver.MustParse("2.1.0")),
10    }
11}

內部程式應寫成：

1if caps.SupportsStreaming {
2    return useStreaming(ctx)
3}
4
5return usePolling(ctx)

這比到處寫 if version >= ... 更清楚，也更容易測試。版本字串是外部事實，capability 是內部行為判斷。

【策略】gate 關閉時要有降級策略

Feature gate 的核心問題是關閉時要做什麼。常見策略包括降級、回錯、隱藏入口、排程稍後處理。

策略	行為	適用情境
fallback	使用舊流程	新能力只是效率改善
reject	回明確錯誤	功能沒有安全替代方案
hide	不註冊 endpoint 或不顯示入口	使用者不應看到該功能
store for later	先保存，稍後處理	即時能力暫不可用但資料不能丟

例如即時推送關閉時，可以改成保存待處理資料：

1func (p Publisher) Publish(ctx context.Context, event DomainEvent) error {
2    if p.realtimeEnabled {
3        return p.realtime.Publish(ctx, event)
4    }
5
6    return p.repository.SaveForLater(ctx, event)
7}

降級策略要符合資料語意。不能即時送出不代表可以直接丟掉重要事件。

【執行】HTTP endpoint 可用 gate 控制註冊或行為

HTTP feature gate 的核心選擇是「不註冊 endpoint」或「註冊但回明確錯誤」。兩者語意不同。

不註冊 endpoint：

1if features.Diagnostics {
2    RegisterDiagnostics(mux, true)
3}

適合診斷入口、內部工具或不希望使用者看見的功能。

註冊但回錯：

 1func HandleRealtimeExport(features Features) http.HandlerFunc {
 2    return func(w http.ResponseWriter, r *http.Request) {
 3        if !features.RealtimePush {
 4            http.Error(w, "realtime export is disabled", http.StatusNotImplemented)
 5            return
 6        }
 7
 8        startRealtimeExport(w, r)
 9    }
10}

適合公開 API，讓呼叫端知道功能存在但目前不可用。

【策略】gate 不應散落成巢狀 if

Feature gate 的核心維護風險是判斷散落在多層呼叫中，最後沒人知道功能到底何時啟用。

反模式：

1if os.Getenv("FEATURE_REALTIME_PUSH") == "1" {
2    if version >= "2.0.0" {
3        if user.Enabled {
4            // ...
5        }
6    }
7}

較清楚的做法是先組出 decision：

 1type RealtimeDecision struct {
 2    Enabled bool
 3    Reason  string
 4}
 5
 6func DecideRealtime(features Features, caps Capabilities) RealtimeDecision {
 7    if !features.RealtimePush {
 8        return RealtimeDecision{Enabled: false, Reason: "feature_disabled"}
 9    }
10    if !caps.SupportsStreaming {
11        return RealtimeDecision{Enabled: false, Reason: "streaming_not_supported"}
12    }
13    return RealtimeDecision{Enabled: true}
14}

Decision 物件讓 log、測試與錯誤回應都能使用相同 reason。

【執行】log 要記錄 gate decision

Feature gate 的核心操作需求是知道功能為何啟用或關閉。當 gate 影響行為時，應記錄穩定 reason。

1decision := DecideRealtime(features, caps)
2logger.Info("realtime decision",
3    "feature", "realtime_push",
4    "enabled", decision.Enabled,
5    "reason", decision.Reason,
6)

這能回答「功能為什麼沒有走即時推送」這類問題。Reason 應是小集合，不要塞完整錯誤字串。

【測試】開與關兩條路徑都要測

Feature gate 測試的核心規則是同時測啟用與停用路徑。只測預設值很容易讓另一條路徑壞掉。

停用路徑：

 1func TestHandleRealtimeExportFeatureDisabled(t *testing.T) {
 2    req := httptest.NewRequest(http.MethodPost, "/export", nil)
 3    rec := httptest.NewRecorder()
 4
 5    handler := HandleRealtimeExport(Features{RealtimePush: false})
 6    handler.ServeHTTP(rec, req)
 7
 8    if rec.Code != http.StatusNotImplemented {
 9        t.Fatalf("status = %d, want %d", rec.Code, http.StatusNotImplemented)
10    }
11}

啟用路徑：

 1func TestDecideRealtimeEnabled(t *testing.T) {
 2    decision := DecideRealtime(
 3        Features{RealtimePush: true},
 4        Capabilities{SupportsStreaming: true},
 5    )
 6
 7    if !decision.Enabled {
 8        t.Fatalf("realtime should be enabled, reason %q", decision.Reason)
 9    }
10}

環境變數解析應單獨測 LoadFeaturesFromEnv。功能測試應直接傳入 Features，不要依賴全域環境狀態。

本章不處理

本章先處理服務內部的 gate 行為邊界；遠端 feature flag 平台與灰度流程，會在下列章節再往外延伸：

Backend：部署平台與網路入口

和 Go 教材的關係

這一章承接的是 composition root、handler boundary 與 runtime gate；如果你要先回看語言教材，可以讀：

小結

Feature gate 是生產操作工具，也是程式設計邊界。好的 gate 會集中載入、轉成 capability、定義降級策略、輸出穩定 reason，並同時測試開與關兩條路徑。它控制的是行為合約，不只是把新程式碼藏在 if 後面。

7.4 Observability pipeline、metrics 與 tracing

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

Observability pipeline 的核心責任是把服務訊號整理成可查詢、可聚合、可關聯的診斷資料。Log schema 描述單次事件，metrics 描述趨勢，trace context 描述跨元件路徑，profile 描述 runtime 成本；它們的責任不同，但應使用一致的識別欄位串起來。

本章目標

學完本章後，你將能夠：

分辨 log、metric、trace 與 profile 各自回答什麼問題
設計穩定的 correlation 欄位
讓 Go 服務輸出適合聚合的診斷訊號
在產生端控制敏感資料進入觀測管線
了解 dashboard 與 alert 為什麼需要依賴穩定欄位

前置章節

後續撰寫方向

Log、metric、trace、profile 分別回答哪些問題。
request_id、event_id、trace_id、span_id 與 correlation_id 如何分工。
OpenTelemetry 導入時，Go 程式碼應保留哪些清楚邊界。
Sensitive data policy 如何套用到 log、trace attribute 與 error event。
Dashboard 與 alert 應依賴穩定欄位，讓查詢與告警規則可以被重複執行。

【觀察】診斷資料要先可關聯，再談漂亮

Observability pipeline 的第一個要求是關聯能力。Log、metric、trace 的格式可以各自精緻，但欄位需要對齊，才能把同一筆請求、同一個事件、同一條 goroutine 路徑串起來。

通常會先建立幾個穩定欄位：

request_id
event_id
trace_id
span_id
user_id 或 tenant_id

【判讀】不同訊號回答不同問題

log：這次發生了什麼。
metric：這類事件發生得多不多、快不快、慢不慢。
trace：它在多個元件之間怎麼走。
profile：CPU、記憶體、goroutine 與等待成本落在哪裡。

如果某個問題要靠自由文字 log 去猜，通常代表欄位設計還不夠穩。

【策略】敏感資料要在產生端就攔住

敏感資料政策應在產生端執行。Go 服務應該在輸出 log 或 trace attribute 前就決定哪些資訊可以外送。

常見要注意的資料有：

token
email
身分證號
raw payload
內部路徑與配置

【執行】結構化 log 是 pipeline 的起點

當 Go 服務使用結構化 log 時，最重要的是欄位穩定與語意清楚。這些 log 後面可能會被：

集中式 log system 搜尋
metric extraction 轉成趨勢指標
alert rule 用來偵測異常

所以 log 欄位要維持穩定命名，分類資訊要放在結構化欄位裡。

【延伸】診斷和容量規劃要串在一起

觀測資料不只是事後排障，也會反過來影響容量規劃與 release 判斷。當你看到 goroutine 數、queue lag、DB latency 或 retry rate 持續變高，就代表系統邊界已經開始吃緊。

本章不處理

本章不會綁定特定 observability SaaS。教材重點會放在 Go 服務如何輸出穩定訊號，讓不同收集平台都能使用。

和 Go 教材的關係

這一章承接的是 Go 的結構化日誌與 runtime 診斷；如果你要先回看語言教材，可以讀：

模組四：架構邊界與事件系統

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

架構邊界的核心目標是讓每個元件只承擔一種責任。事件來源負責接收外部訊號，normalize 階段負責轉成內部事件，processor 負責套用規則，repository 負責保存狀態真相，publisher 負責把結果送出去。

事件驅動不是把所有東西都丟進 channel。Go 的事件系統需要明確的型別、清楚的擁有者、可測的狀態轉移，以及能在多來源輸入下維持一致的處理流程。

本模組承接入門篇的 practical 與 refactoring：前面學會新增事件、建立 repository port、拆 handler、整理 domain package；這裡進一步處理「系統開始變大後，事件與狀態如何不失控」。

章節列表

章節	主題	關鍵收穫
4.1	事件來源、處理流程與狀態邊界	用邊界拆開 reader、normalizer、processor、repository、publisher
4.2	事件去重與語義鍵設計	用 domain key、時間窗口與清理策略管理重複事件
4.3	Source of Truth：狀態邊界	集中狀態轉移、保護可變資料、設計 projection
4.4	多來源 event 融合	把 HTTP、queue、timer 等來源收斂到同一套 domain event 流程

本模組使用的範例主題

本模組使用虛構的通知與工作處理服務作為範例。服務可能從 HTTP callback、queue message、timer 或檔案 reader 收到事件，最後更新內部狀態並推送通知。

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

本模組的 Go 核心概念

用 struct 定義穩定的內部事件模型。
用 interface 表達 reader、repository、publisher 這類能力。
用 context 傳遞 request lifecycle、取消與逾時。
用 mutex 或單一 goroutine 保護共享狀態。
用 package 邊界限制 adapter、application、domain 的依賴方向。
用 table-driven test 驗證 normalize、dedup 與狀態轉移。

學習重點

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

外部訊號是否應該轉成 domain event
去重應該使用哪些欄位，哪些欄位不應進入 key
狀態真相應該由哪個元件擁有
新事件來源應該新增 adapter，還是修改 processor
ports/adapters 與 event-driven service 如何在 Go 中自然結合

章節粒度說明

本模組的四章分別處理事件系統的四個核心面向，不建議硬拆成更小的孤立段落。事件來源、去重、狀態真相與多來源融合會互相影響；拆得太碎會讓讀者看不到一筆事件如何從外部輸入走到狀態更新與推送。

閱讀時可以把四章視為一條路線：

事件來源、處理流程與狀態邊界：先建立元件分工。
事件去重與語義鍵設計：再定義「同一事件」的語意。
Source of Truth：狀態邊界：接著決定誰能改狀態。
多來源 event 融合：最後處理 HTTP、queue、timer 等多入口協作。

本模組不處理

本模組不實作完整 message queue、分散式 transaction 或 event sourcing 平台。這些主題需要更多基礎設施與操作細節；本模組先聚焦 Go 程式內部如何建立清楚的事件與狀態邊界。後續可接資料庫 transaction 與 schema migration 以及 Durable queue、outbox 與 idempotency。

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

7.5 Kubernetes、systemd 與 load balancer 合約

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

部署平台合約的核心責任是讓 Go 服務的生命週期和外部調度系統對齊。程式內部需要清楚的 context、shutdown timeout、readiness、health / liveness 與 memory limit；Kubernetes、systemd、load balancer 或雲端平台則決定這些訊號何時被觸發與如何被解讀。

本章目標

學完本章後，你將能夠：

理解 shutdown、readiness 與 connection draining 的順序
看懂平台 timeout 對 Go server 的影響
分辨 health 與 readiness 的不同責任
把 memory limit 與 Go runtime 的資源管理接在一起
讓部署平台和程式彼此遵守同一份合約

前置章節

後續撰寫方向

SIGTERM、shutdown timeout、readiness false 與 connection draining 的順序。
Kubernetes terminationGracePeriodSeconds 與 Go http.Server.Shutdown 如何配合。
Load balancer idle timeout 如何影響 WebSocket heartbeat 參數。
Container memory limit、Go memory limit 與 OOM killer 之間的關係。
systemd restart policy 與 health endpoint 的責任分工。

【觀察】平台會主動改變服務生命週期

Go 程式不會在真空裡執行。Kubernetes、systemd、load balancer、container runtime 都會影響服務何時接新請求、何時開始收尾、何時被強制終止。這表示程式不只要「能跑」，還要能跟平台協調。

常見的生命週期訊號有：

SIGTERM
readiness false
HTTP shutdown
connection draining
memory pressure

【判讀】health 與 readiness 有不同合約

health 通常表示服務自己還活著，readiness 則表示它是否適合接新流量。

health 可以用來讓平台知道 process 還活著。
readiness 可以用來讓 load balancer 停止送新請求。

如果兩者混在一起，部署時就容易出現「服務還沒收尾就被塞新流量」或「其實還能接流量卻被誤判下線」的問題。

【策略】shutdown 應該是可預期流程

典型的 shutdown 順序是：

接收到停止訊號。
先把 readiness 關掉。
停止接新流量。
讓現有 request / worker / websocket 收尾。
超時後強制結束。

這個順序能讓平台有時間把流量移走，也讓應用有時間清理資源。

【執行】資源限制要和 runtime 觀念一起看

container memory limit 不只是部署平台的事，也會影響 Go runtime 的行為。當可用記憶體變少時，應用更需要控制：

goroutine 數量
buffer 大小
cache 體積
in-memory queue 長度

如果這些沒有限制，平台的 OOM killer 可能會比你的 graceful shutdown 先來。

【延伸】平台合約要被測試

部署平台合約需要在測試或預備環境驗證。至少要確認：

shutdown 時 request 是否停止接入
worker 是否有機會收尾
WebSocket 是否有 close path
health 與 readiness 是否分工清楚

本章不處理

本章不會完整教 Kubernetes 或 systemd 操作。重點是讓 Go 程式設計能清楚暴露平台需要的生命週期訊號。

和 Go 教材的關係

這一章承接的是 Go 的 shutdown 與 runtime 限制；如果你要先回看語言教材，可以讀：

模組五：測試與可靠性

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

並發服務測試的核心目標是讓時間、連線、goroutine、共享狀態與錯誤路徑變得可重現。只測 happy path 不足以保護長時間運行的 Go 服務；真正需要測的是取消、timeout、queue full、cleanup、data race 與協定邊界。

本模組承接前面的並發、WebSocket 與架構邊界：時間注入讓狀態轉移可測，WebSocket integration test 驗證真實連線互動，race detector 檢查共享狀態，table-driven test 幫助案例保持清楚。

章節列表

章節	主題	關鍵收穫
5.1	時間注入與狀態轉移測試	不用 sleep 也能測 timeout、deadline 與狀態轉移
5.2	WebSocket integration test	用真實 test server 驗證 client/server 協定
5.3	race condition 檢查	用 `go test -race` 搭配併發測試找資料競爭
5.4	table-driven test 的設計邊界	讓測試表只描述單一行為維度

本模組使用的範例主題

本模組使用虛構的即時通知服務作為範例。範例包含 job 狀態轉移、WebSocket subscribe flow、client cleanup、repository concurrent access 與 topic normalization。

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

本模組的 Go 核心概念

用 now time.Time 或 func() time.Time 控制時間。
用 httptest.Server 建立真實 WebSocket integration test。
用 read/write deadline 避免測試永久卡住。
用 eventually helper 等待非同步清理，而不是固定 sleep。
用 go test -race ./... 檢查執行到的 data race。
用小而清楚的 table-driven test 表達同一個行為的多組案例。

學習重點

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

哪些邏輯應該用純函式測，哪些需要 integration test
測試裡的時間應該如何注入，而不是等待真實時間
WebSocket 測試如何避免永久卡住
race detector 能找什麼，不能證明什麼
table-driven test 何時該拆成多個測試

本模組不處理

本模組不建立完整測試框架，也不討論大型 CI 平台、壓力測試或 chaos testing。這些主題很重要，但本模組先聚焦單一 Go 服務內最常見、最容易失控的可靠性測試；後續可接 CI、fuzz、load test 與 chaos testing。

學習時間

預計 3-4 小時

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

7.6 CI、fuzz、load test 與 chaos testing

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

可靠性驗證流程的核心責任是讓不同層級的測試回答不同風險。Unit test 驗證規則，integration test 驗證協定協作，race test 檢查資料競爭，fuzz test 尋找輸入邊界，load test 驗證容量，chaos test 驗證失敗復原。

本章目標

學完本章後，你將能夠：

分辨不同測試層級各自要防的風險
把 race、fuzz、load 與 chaos 放到合適的流程裡
設計能回饋容量規劃的驗證流程
不把端到端測試當成萬能答案
讓測試結果回到 deployment 與 runtime 邊界

前置章節

後續撰寫方向

CI 中哪些測試應每次執行，哪些可以排程或合併前執行。
Fuzzing 適合驗證 parser、normalizer 與 protocol decoder 的哪些邊界。
Load test 如何設定 client 數、message rate、payload size 與觀測指標。
Chaos testing 如何模擬 broker 斷線、資料庫延遲、server shutdown 與網路抖動。
測試結果如何回饋到 capacity planning 與 feature gate。

【觀察】不同測試層級回答不同問題

可靠性驗證最怕的錯誤，是把所有測試都塞成一種樣子。不同層級應該分工：

unit test：規則有沒有寫對
integration test：協定與元件有沒有接對
race test：並發邊界有沒有資料競爭
fuzz test：輸入邊界有沒有漏掉
load test：容量與延遲是否能接受
chaos test：失敗發生時系統能不能復原

【判讀】race test 是輔助檢查

go test -race 能抓出實際跑到的資料競爭，但它不是正確性保證。真正的重點仍然是：

state owner 是誰
哪些資料需要 lock
哪些資料應該只讓單一 goroutine 擁有
哪些資料應該複製而不是共享

【策略】load test 的輸出要能回到容量判斷

load test 不應只是跑出一個數字，還要能回答：

哪個 queue 開始變長
哪個 DB connection pool 開始飽和
哪種 message rate 會讓 latency 明顯上升
哪個 memory curve 表示需要調整 buffer 或 GC 參數

如果沒有這些觀察點，壓測結果就很難轉成實際修正。

【執行】chaos test 應該模擬真實失敗

chaos test 的重點是模擬真實世界常見的失敗：

broker 暫時不可用
database 延遲上升
shutdown 中斷流量
網路抖動或 timeout

這些情境應該回到 graceful shutdown、retry、idempotency 與 backpressure 設計。

【延伸】測試結果應回饋到 feature gate

如果某個功能在 load test 或 chaos test 下風險太高，最直接的做法不一定是先修完整系統，也可能是先用 feature gate 逐步推出、觀察與回收。

本章不處理

本章不會綁定特定 CI 或壓測平台。教材重點會放在測試層級分工，避免把所有風險都塞進端到端測試。

和 Go 教材的關係

這一章承接的是 Go 的並發測試與可靠性驗證；如果你要先回看語言教材，可以讀：

模組六：生產操作

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

生產操作的核心目標是讓 Go 服務可停止、可觀測、可診斷、可漸進啟用功能。服務能在本機跑起來只是第一步；長時間運行後，真正重要的是 shutdown 是否可預期、監控訊號是否清楚、log 是否可查詢、功能開關是否有降級策略。

本模組承接前面的並發、WebSocket、runtime 與測試：graceful shutdown 需要 context 和 goroutine lifecycle，health endpoint 需要區分可用性與診斷，structured log 需要能追 event flow，feature gate 需要能安全控制新能力。

章節列表

章節	主題	關鍵收穫
6.1	graceful shutdown 與 signal handling	用 signal、context、timeout 與 owner cleanup 停止服務
6.2	健康檢查與診斷 endpoint	區分 health、readiness、diagnostics 與 status code 合約
6.3	結構化日誌欄位設計	用穩定欄位讓 log 可 grep、可聚合、可追蹤
6.4	版本偵測與 feature gate	用功能開關、能力偵測與降級策略控制行為

本模組使用的範例主題

本模組使用虛構的即時通知服務作為範例。範例包含 HTTP server、WebSocket hub、background worker、runtime diagnostics、structured log 與 feature gate。

範例只用來展示 Go 生產操作設計，不假設讀者正在維護任何特定專案。

本模組的 Go 核心概念

用 signal.NotifyContext 或 signal channel 建立 root context。
用 http.Server.Shutdown 停止接受新 request。
用 context 傳遞停止訊號給 worker、hub、WebSocket pump。
用 /health、/ready、/debug/... 分開不同操作訊號。
用 log/slog 建立穩定 structured fields。
用 config struct 載入 feature gate，而不是到處讀環境變數。

學習重點

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

服務收到停止訊號後，哪些元件要先停止接流量
health、readiness、diagnostics 各自回答什麼問題
structured log 欄位如何支援查詢與聚合
哪些資料不應進入 log
feature gate 關閉時應降級、回錯、隱藏還是排程稍後處理

本模組不處理

本模組不討論 Kubernetes、systemd、雲端平台或完整 SRE 流程的所有細節。這些環境會影響操作策略，但本模組先建立 Go 服務本身應具備的操作邊界；後續可接 Kubernetes、systemd 與 load balancer 合約以及 Observability pipeline、metrics 與 tracing。

模組七：跨節點與平台整合

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

跨節點與平台整合的核心目標是把「單一 Go process 內的正確邊界」延伸到外部基礎設施。前六個模組先建立 goroutine lifecycle、WebSocket 連線、runtime 診斷、事件邊界、測試與操作語意；本模組處理服務進入多節點、多資料來源、多觀測工具與部署平台後會出現的新責任。

本模組已開始補成正文。章節先定義問題邊界與前置脈絡，再逐步補上 transaction、outbox、跨節點 WebSocket、observability、部署與可靠性驗證的實作語意；後續仍可依實戰需求繼續擴寫。

與 Backend 教材的分工

本模組保留在 Go 進階篇，因為它要回答的是「Go 服務跨出單一 process 前，程式內部需要準備哪些 port、訊號、錯誤語意與測試合約」。具體資料庫、Redis、RabbitMQ、observability、Kubernetes 或 CI 平台操作，會放在跨語言的 Backend 服務實務指南。

章節列表

章節	主題	承接問題	Backend 實作
7.1	資料庫 transaction 與 schema migration	狀態邊界進入持久化層後如何維持一致	資料庫與持久化
7.2	Durable queue、outbox 與 idempotency	事件跨 process 後如何避免遺失、重複與半成功	訊息佇列與事件傳遞
7.3	跨節點 WebSocket、presence 與重連協定	多台 server 如何管理訂閱、推送與連線狀態	快取與 Redis、訊息佇列
7.4	Observability pipeline、metrics 與 tracing	log、metric、trace 如何組成可操作的診斷系統	可觀測性平台
7.5	Kubernetes、systemd 與 load balancer 合約	部署平台如何影響 shutdown、health 與資源限制	部署平台與網路入口
7.6	CI、fuzz、load test 與 chaos testing	測試如何從單一行為擴展到系統可靠性	可靠性驗證流程

本模組和前面章節的關係

本模組適合在你已經理解單一 Go 服務的內部邊界後閱讀，用來補足生產環境常見的外部系統責任。

事件與狀態邊界先讀模組四：架構邊界與事件系統。
WebSocket lifecycle 先讀模組二：WebSocket 服務架構。
測試可靠性先讀模組五：測試與可靠性。
操作語意先讀模組六：生產操作。

學習時間

目前已可作為第一輪正文閱讀，完整學習時間可隨後續擴寫再調整。

Go 進階指南

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

本系列是接在入門教學之後的延伸路線，目標是把 Go 的並發模式、WebSocket 服務架構、runtime 診斷、狀態邊界與生產環境可觀測性講到能真正用在服務上。語法細節留在入門篇；進階篇聚焦長時間服務會遇到的設計壓力。

目標讀者

已完成 Go 入門實戰指南的工程師
想深入理解 Go 並發模型與 runtime 行為的開發者
需要維護長時間運行服務的人
想把 Go 服務從「能跑」提升到「可觀測、可測、可演進」的人

學習目標

掌握 goroutine、channel、mutex 的進階使用邊界
理解 WebSocket client lifecycle、heartbeat、buffer 與慢客戶端問題
使用 pprof、runtime 記憶體限制與結構化日誌診斷服務
設計 event-driven service 的資料邊界與去重策略
建立並發測試、整合測試與可重現的時間控制
能評估 Go 服務在生產環境的風險與操作策略
知道單一 Go 服務延伸到跨節點與平台整合時，哪些責任會轉移到資料庫、queue、broker、observability pipeline 與部署平台

共用術語

進階篇延續入門篇的 action、command、domain event、repository、port、adapter、projection 等詞彙。若你需要確認這些詞在這套教材中的責任邊界，可以先回到 Go 教材核心術語。

與 Backend 教材的分工

Go 進階篇處理單一 Go 服務內部的高階能力：goroutine lifecycle、WebSocket pump、runtime 診斷、event boundary、race test、graceful shutdown 與 diagnostics endpoint。當內容開始碰到資料庫、Redis、RabbitMQ、Kafka、OpenTelemetry、Kubernetes 或 CI 平台操作時，就應該轉到跨語言的 Backend 服務實務指南。

模組七保留在進階篇裡，因為它要回答「Go 服務在跨出去以前，還需要先把哪些 port、訊號與測試合約準備好」。外部系統本身的選型與部署細節，則放在 Backend，讓不同語言都能共用同一套實作知識。

學習路徑

路徑 A：並發服務維護者

1模組一 → 模組四 → 模組五

重點：事件流、共享狀態、並發測試。

路徑 B：WebSocket/API 開發者

1模組二 → 模組六 → 模組五

重點：連線生命週期、訊息路由、操作診斷。

路徑 C：效能與可靠性工程師

1模組三 → 模組五 → 模組六

重點：pprof、goroutine leak、race check、服務操作。

路徑 D：完整學習

1模組一 → 模組二 → 模組三 → 模組四 → 模組五 → 模組六 → 模組七

按順序學習，建立完整的 Go 長時間運行服務模型。

主題延伸地圖

進階篇的章節會反覆碰到 log、time、state、event、WebSocket 與 testing。這些主題會在不同服務壓力下承擔不同責任；主題延伸地圖用來幫讀者辨識每一層的分工。

主題	單一 process 內的設計	生產操作	跨節點邊界	Backend 實作
並發與容量	channel ownership、select loop、非阻塞送出	race condition 檢查、graceful shutdown	可靠性驗證流程	Backend：可靠性驗證
WebSocket	read/write pump、heartbeat、慢客戶端	WebSocket integration test、health diagnostics	跨節點 WebSocket	Backend：快取與 Redis、訊息佇列
Runtime 診斷	GC 與 memory limit、pprof、goroutine leak	diagnostics endpoint	Observability pipeline、部署平台合約	Backend：可觀測性平台、部署平台
事件與狀態	component boundaries、source of truth、event fusion	結構化日誌欄位	outbox 與 idempotency、資料庫 transaction	Backend：資料庫、訊息佇列
測試分層	時間控制、table-driven test	race check、integration test	可靠性驗證流程	Backend：可靠性驗證

先備知識

本系列假設你已經完成 Go 入門實戰指南的基礎部分，因為下面這些章節會直接沿用那些概念：

每章結構

每章都採用「由淺到深」的結構，先說明問題，再切到設計與實作：

原理層：這個機制解決什麼問題
設計層：在服務架構中如何切責任
實作層：用簡化範例程式碼看具體做法
實戰檢查：維護時要確認哪些風險

文件版本：v0.1.0 最後更新：2026-04-22 系列狀態：核心初稿完成，延伸模組規劃中