本章目標

學完本章後，你將能夠：

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

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

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

常見現象：

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

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

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

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

1GOGC=100 go run ./cmd/server

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

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

【判讀】memory limit 是 runtime 軟目標

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

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

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

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

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

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

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

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

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

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

簡單方式可以用 runtime.ReadMemStats：

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

測試：

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

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

本章不處理

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

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

和 Go 教材的關係

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

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

小結

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

本章目標

學完本章後，你將能夠：

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

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

pprof 診斷的核心起點是先確認你要回答哪個問題。不同 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 給的是線索，不是最終修正。修正要回到資料模型、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 診斷的核心流程是先保留現場，再改程式。若你先重啟服務或調參，可能會清掉最重要的證據。

建議流程：

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

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

本章不處理

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

• Go 進階：Observability pipeline、metrics 與 tracing
• Backend：可觀測性平台

和 Go 教材的關係

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

• Go：goroutine：輕量並發工作
• Go：select：同時等待多種事件
• Go：如何新增背景工作流程
• Go：狀態管理的安全邊界

小結

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

本章目標

學完本章後，你將能夠：

1. 分辨合理長期 goroutine 與 goroutine leak
2. 用 context、done channel、connection close 設計退出路徑
3. 用 pprof goroutine profile 判讀卡住 stack
4. 測試 worker、ticker、WebSocket pump 是否能退出
5. 從 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 都能回答三個問題：

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

若三題任一題答不出來，就有 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 後，下一步是回到對應 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 進階：channel ownership 與關閉責任
• Go 進階：bounded worker pool
• Go 進階：select loop 的生命週期設計

和 Go 教材的關係

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

• Go：goroutine：輕量並發工作
• Go：channel：資料傳遞與 backpressure
• Go：select：同時等待多種事件
• Go：如何新增背景工作流程

小結

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

本章目標

學完本章後，你將能夠：

1. 理解 allocation 如何增加 GC 壓力
2. 分辨必要 copy boundary 與不必要重複配置
3. 用預配置降低 slice 成長成本
4. 判斷 JSON marshal 與 WebSocket payload 的重用邊界
5. 用 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，配置與延遲都會隨資料量線性成長。

可選策略：

優化資料形狀通常比取消 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

若 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 混用。

較安全的優化順序：

1. 用 pprof 確認熱點。
2. 預配置已知大小的 slice/map。
3. 減少重複 marshal。
4. 改 API 資料形狀，例如分頁或 projection。
5. 最後才考慮 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 入門：struct 與 JSON tag
• Go 入門：slice 與 map
• Go 入門：指標與資料複製邊界
• Go 進階：pprof 基礎診斷流程

和 Go 教材的關係

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

• Go：如何擴展狀態投影欄位
• Go：如何新增 repository port
• Go：如何新增一個即時訊息 action
• Go：狀態管理的安全邊界

小結

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